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 : ianb@??? : http://blog.ianbicking.org
_______________________________________________
Paste-users mailing list
Paste-users@???
http://webwareforpython.org/cgi-bin/mailman/listinfo/paste-users
