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? Increasing the quantity and quality of official published documentation on the project is a massive undertaking - regardless of how it is done and with what tools. I'd rather we started in the other end by agreeing on what documentation we (and plugin providers) should provide to the community of users and developers. It then becomes easier to evaluate and discuss individual tools for the job. :::simon https://www.coderesort.com --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Trac Development" 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/trac-dev?hl=en -~----------~----~----~----~------~----~------~--~---
