[Trac-dev] Re: Sphinx?

osimons wrote:
> 
> On May 14, 2:29 pm, "Alec Thomas" <a...@swapoff.org> wrote:
>> 2008/5/14 Noah Kantrowitz <kan...@rpi.edu>:
>>
>>> 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