Bruno J. M. Melo wrote:
> Hello Ian,
>
> I think these questions are very related with my GSoC project [1], and
> ideas like yours are welcome to make me work even more effectively
> during this summer :D
>
> With Sphinx we can create extensions that could generate metadata about
> versions, or develop reST directives to reference to others
> documentations using the right version.
Well, my thoughts were more mechanical than this. You'd do something
during the upload process to upload to, say, htdocs/1.0.5/, and then
symlink htdocs/current/ to that version or something like that. You'd
also have to do something so that anything that *isn't* current gets a
warning on it (including the docs for the unreleased version, which
might get uploaded periodically into htdocs/devel/). The actual current
docs maybe would redirect? That is, if 1.0.5 is the current version,
would a request to /1.0.5/some-doc.html redirect to /some-doc.html? I'm
not sure. I have strong feelings that documents should have a canonical
URL.
For inter-project linking, I figured that maybe you could say via
configuration that all references to webob should be resolved with some
base URL, that might or might not be project-specific. When you release
a version you'd pin the links to that specific location, so that as new
versions are released you'd still point to the version you actually
expect to use together. So if TG is released, it'd pin the Pylons,
WebOb, etc. versions. (Though if you could actually pin the installed
versions of packages this would be a more accurate representation... but
that's a separate issue.)
I'm not exactly clear how Sphinx does linking. Probably a base URL is
more naive than what it does. But maybe packages can publish an index
or something that can be used to handle the linking.
> I didn't understand exactly how backlinks could be used... only to
> persist information about references? or create sections like 'see also'?
Mostly to be handy, as I think backlinks are a useful way to browse
documentation. But also perhaps they could facilitate linking back to
TG or Pylons documentation in a comfortable way.
> [1] http://www.dubita.com/pub/GSoC2008_BrunoJMMelo.txt
Ack, no word wrap!
Did you read Zed Shaw's recent post on docs? Seems like he's thinking
about similar things.
--
Ian Bicking : ianb@??? : http://blog.ianbicking.org
_______________________________________________
Paste-users mailing list
Paste-users@???
http://webwareforpython.org/cgi-bin/mailman/listinfo/paste-users
