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