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 : [EMAIL PROTECTED] : http://blog.ianbicking.org _______________________________________________ Paste-users mailing list [email protected] http://webwareforpython.org/cgi-bin/mailman/listinfo/paste-users
