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. I didn't understand exactly how backlinks could be used... only to persist information about references? or create sections like 'see also'? [1] http://www.dubita.com/pub/GSoC2008_BrunoJMMelo.txt On Fri, May 2, 2008 at 1:53 PM, Ian Bicking <[EMAIL PROTECTED]> wrote: > > So, I think we're all interested in using Sphinx for documenting our > projects. Well, I'm not sure about TG, but I know Ben is converting > Pylons, and I'm planning to convert my projects (I got Paste setup so > far, but not uploaded anywhere). > > Right now Ben is including documentation for some projects (like webob) > directly on pylonshq, and I'm guessing that he's planning on adding more > libraries. > > I'm not sure how I feel about this. In the case of a library that is > managed by someone else and isn't going to be Sphinx-documented, that's > fine (e.g., simplejson, as I don't know if there's any plans to change > over its docs). But if webob documentation gets mirrored all over the > place, that does bother me a bit. I dislike the ambiguity of the > situation, where you could google for webob docs and get identical docs > at a variety of locations, and easily come upon documentation for old > versions without realizing that's what you had gotten. > > I understand the reasons for mirroring them too. To document the > version of a library that you are using in your framework, to easily > link to reference documentation using the Sphinx conventions, and to > have navigation that is consistent across all the documentation. > > I'm not sure what the middleground is. For old versions, some Sphinx > configuration to put strong notices in the template about the status of > the version would do it. With linking, it might be resolvable with a > modest amount of programming effort, if we could tell Sphinx how to link > certain packages. That would still leave navigation unresolved, which > unfortunately I have no solution for. I'm quite open the idea of some > consistent styling so that the move from site to site isn't jarring, but > that still doesn't give backlinks. > > Backlinks actually *would* be a sort of solution, and could be > interesting. That is, if every page pointed to all the pages that point > to it. This wouldn't be open backlinking, just closed among a whitelist > of sites (and maybe a specifically maintained list too, for things like > blog posts?) That wouldn't make the navigation exactly consistent, but > maybe close enough? > > -- > Ian Bicking : [EMAIL PROTECTED] : http://blog.ianbicking.org > > > > -- bruno j. m. melo http://brunojm.googlepages.com >> brunojm <at> gmail.com << --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears Trunk" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/turbogears-trunk?hl=en -~----------~----~----~----~------~----~------~--~---
