[Trac-dev] Re: Sphinx?

Christian Boos wrote:
> Bottom line:
> Improving the documentation system for Trac should motivate us to make 
> Trac better at writing documentation, not prompt us to ditch Trac in 
> favor of another tool for doing that job.

This was discussed in depth a while ago, but I will sum up the key 
points here.

1) A wiki exists for communication, taking quick notes, and to act as a 
general buffer between both developers and the community. It is _not_ a 
system to write good technical documentation. We have optimized both our 
wiki syntax and editing system to match these intentions IMO, so I don't 
consider this a problem. Some documents which need rapid editing from 
many people will remain better suited to being in the wiki, an example 
being the proposals that live under TracDev. Our actual documentation is 
another story. One big reason to move to ReST files in Subversion is we 
gain easy branching, thus warding off the current insanity with 
0.1[012]/* page names and such. It also allows us to move to a 
submit-a-patch workflow as we do with code. Documentation is just as 
critical as any other part of the project, and as much as I like 
community involvement, it has become clear through experience that wikis 
do not work for our needs. ReST has an existing and powerful 
documentation toolchain that very closely matches our needs, so I think 
it is a logical fit. We will indeed be "eating our own dogfood", as the 
newhelp system designed for this will be exposed to projects using Trac 
for their own documentation needs (with the t.e.o methodology and 
toolchain serving as an example of how to use it).

Now to get back to the original topic at hand, I am happy with Sphinx 
and I think we should use it for our toolchain. The TOC and index 
systems are very nice and easy to use. I played around a bit with the 
autodoc extension, and it works quite nicely for pulling docs in from 
the source code, and makes it easy to add manual tweaks here and there.

I currently see things being broken into 4 main doc trees: guide (user 
docs), admin (administration guide), install (install process), and api 
or dev (developer reference and tutorials).

--Noah