osimons wrote: > Install and Developer guides > ---------------------------- > > ... > > And, as noted above, we should make some effort to make a nicer > template that suits us and used for all the Sphinx-generated guides... >
The Genshi/epydoc related stylesheets could eventually be of some help here, as they already deal with the docutils classes (see http://svn.edgewall.org/repos/edgewall/tools/doc/style/). > These guides are English only as I see it. > > User and Admin guides > --------------------- > > ... > > The content pulled in for rendering inside Trac obviously needs to be > renderable. Sphinx-customized rst files are currently not as they > throw all kinds of errors when Sphinx is not installed. I think we all > agree that Sphinx should not be a requirement for a vanilla > installation, so we need to figure something out here. > > The current newhelp is format agnostic as long as it know the mimwtype > and has a renderer for it, so I supose the alternatives are: > > a) Have Sphinx generate the input that we use inside Trac. This can be > plain HTML output, or it can possibly be 'stipped down' rst so that we > render it in Trac as regular rst. > It should be plain HTML, even a stripped down .rst would still require docutils, which is also an optional dependency. > b) Make a Trac custom mimeview renderer that can read the Sphinx rst > files, stip unneeded directives and render them directly like any > other file. Perhaps just a 'silently ignore errors' setting in rst > renderer is enough? > Same as above, it would require docutils. But that would be very useful on t.e.o itself, nevertheless. > c) Use the current wiki markup for these guides (as today), and make a > Sphinx supported rendering directive that can insert Trac-generated > input into the pages. The Sphinx guide can then just be stubs that > provide the scaffolding and pointers to what main content to provide > inside each main file. > That might eventually be possible one day once we can generate docutils compatible output from wiki markup, but not for now (see also point 3. below). > Àre there other alternatives? > Noah already answered that one: Sphinx provides some support to "compile" the rendered output in pickled files (PickleHTMLBuilder), so we could handle those pickled files just like the .mo files for translations. See http://sphinx.pocoo.org/builders.html#pickle-builder-details > Decisions to be made > -------------------- > > 1) Pluggability with regards to main docs. Currently the online help > is pluggable, so that something like a blog plugin can provide > additional pages available in the online guide. I see no point in > directly extending this to the Sphinx documentation - newhelp should > provide simple mechanisms for providing online help, but if plugin > developers want to make a shiny PDF from Sphinx (or other tools) they > do it on their own. > > Agree? > Yes. (...) > 3) What format do we use for content? Adopting Sphinx for all guides, > it would make by far the most sense to move all documentation to rst. > There are disagreements here, and personally I've been in the camp > that would prefer that we use and improve the current Trac tools and > markup for documentation. However, I'll go with the flow and respect > the decision of what seems to be the majority of votes. > > Is the decision then made to convert all docs to restructured text > (rst)? > Well, I can understand the need for .rst if we want to produce static documentation, as there's no good alternative yet. However I fail to see how the reStructuredText markup in itself is any superior to the Trac wiki markup (in my eyes, it's not), so I think the main differentiator is in the toolchain and the fact that sphinx and docutils bring a lot of added value. Like I said in a previous mail, I think it will eventually be possible to bridge this gap by having Trac generate .rst markup from wiki markup, in the spirit of your point c. above. Of course, this is not yet possible, and so it seems easier to convert all the documentation we have to .rst. One of the positive outcome that could eventually happen during such a conversion is that this could be the occasion to clean-up the existing docs or write new docs (like in trunk/doc/install). But I think only time will tell if all the documentation will be converted and if the documentation can be better maintained in that format. -- Christian --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
