On May 19, 2008, at 8:00 PM, osimons wrote: > > > > On May 19, 7:25 pm, Matt Good <[EMAIL PROTECTED]> wrote: >> I think it's useful to continue discussing ways to improve Trac's >> value as a documentation tool, but that shouldn't stop Noah & others' >> momentum on rewriting the documentation. >> >> Noah's efforts with Sphinx push us in the right direction for how we >> want to distribute the documentation, which is a separate issue from >> how we maintain it. Distributions should include a standalone set of >> documentation in HTML and/or PDF formats and be provided inside the >> application within a new Help module so that they're available even >> when the Wiki has been disabled. >> >> I also hope we can agree that the current free-for-all editing of the >> documentation in the t.e.o Wiki has become unsuitable for maintaining >> well-written docs. Moving them into the source tree with a more >> formal patch acceptance process should help that, so let's let Noah >> continue his current work and start a new discussion for how to >> improve Trac to the point where it's suitable for maintaining the >> docs >> at some point in the future. > > Moving to using the repos as master for documentation is a conclusion > that I think is agreed by all in earlier discussions and earlier in > the thread. As for standalone documentation, it does seem like Sphinx > is a good choice - and of course, any effort to review and improve the > content is most welcome. Reusing help pages for internal rendering and > standalone documentation is surely what we would want. > > The objection I would like to raise at this stage is how this initial > proof-of-concept is committed to trunk. Having created a newhelp > branch (with proposal) and tried an approach to solving it from the > Trac side with flexibility for help page providers of any kind, I do > think Noah shortcuts a process of refinement and issue resolving that > is nowhere near finished. The new pages are committed as fresh pages > without history, they are committed to a 'doc' directory that is > outside the package that gets installed (and won't be available for > internal help), the rst markup expects Sphinx to be insalled and > produces countless errors when using plain trac rst mimeview > rendering, and issues like localization of help pages is not at all > considered. > > We all agree that the docs need fixing, and a number of people are > eager to get it done. I would however prefer that this happened > outside the trunk for the time being so that we can arrive at a full > working solution for all documentation before exposing it in trunk.
I spoke to people about this before starting to make sure it would work for us. Before releasing a version we can use the pickle output builder (or a similar subclass we develop ourselves if this should prove insufficient) to dump the documentation to HTML fragments in a folder structure that will be included in the egg. These would be entirely rendered, so neither docutils not Sphinx will be required on a normal install. This rebuild step can be run from a post-commit hook on trac.edgewall.org to keep it always up to date. These HTML fragments would be what your newhelp system would serve up. The two actually complement each other very nicely IMO. I think this should do exactly what we want, but feel free to point out if I am missing somehthing. --Noah --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
