osimons wrote:
On May 14, 2:29 pm, "Alec Thomas" <[EMAIL PROTECTED]> wrote:2008/5/14 Noah Kantrowitz <[EMAIL PROTECTED]>:What would people think about basing our new docs around the Sphinx system (http://sphinx.pocoo.org/)?It seems to provide a number of nice support functions beyond simply putting each doc in a file and running rst2html or something. The pickle builder would be a good starting place for the integration with osimmion's newhelp interface (I think). This would mean Sphinx and Pygments would be required for building the documentation (and therefore for building release media), but neither would be runtime dependencies. Thoughts?I've been converting the documentation for my own applications to Sphinx, and it's been a very pleasant experience. As a bonus, I think it would also save us a lot of work.Sphinx appeared just after getting draft 1 of the newhelp branch ready, and I agree that it does look promising. I say that having just browsed the front page and some minimal docs, and have no real clue or idea as to how to do this yet. I would need to actually install and play with it, which I just have not found time to do yet. Nor has it been a high priority issue for me to make 'ring-bound' documentation - my main motivation was moving the pages out of the wikis of each project, and rendering them using available Trac mimeviewers depending on format - which is all Trac wiki for the time being. With the plugin architecture for providing help pages + being format agnostic, 'newhelp' tries to make it effortless for others to provide documentation as an ever-increasing part of Trac is provided by plugins. And, add to this the i18n issues of providing some/all the pages localized... Sphinx looks interesting and I will look into it at some stage, but I'm mostly wondering about what problem to actually apply it to? Would it be to run extractions to create development and reference guides - ie. different from the typical user guides that a continuation of the wiki/newhelp provides? Our to collect the usage documentation we have + add lots of documentation we don't have today, and make some sort of official trac-book to accompany major and minor releases?
This would accompany moving from the wiki to ReST-formatted files in Subversion. Sphinx To start with I don't forsee providing any more than the current TracGuide pages do, but a real developer tutorial and guide would be much appreciated I think. We would use sphinx to generate the files served by newhelp (for the trac section of it at least, plugins can use whatever they want as you said).
I've been fooling around with all this for the morning, and I think it will be a very good match for us. I am working on a PoC conversion of some of the install docs to use as an example.
--Noah
signature.asc
Description: OpenPGP digital signature
