[darcs-users] Separating the user manual and code

[Trent W. Buck]

Max,

"Max Battcher" <me at worldmaker.net> writes:
>> - getting consensus on what source format to use (Max and I favour
>> reST, though I don't know if Max wants to get involved in ongoing
>> maintenance of the user manual).
>
> It would certainly be easier for me to contribute documentation
> patches with a reST/Sphinx manual.  I'm tempted to go ahead and create
> a Sphinx config, skeleton and convert over a few choice sections to
> see if an example would help get stronger opinion for/against the
> idea...

It sounds like you're pretty familiar with Sphinx.  I've only used
plain reST and every time I look at the Sphinx documentation, I get
overwhelmed by the API documentation features, which aren't relevant to
a user manual.  What really interested me about Sphinx is the potential
to avoid the problems plain reST has with large documents --
particularly handling multiple source files, cross-referencing,
appendices and lists of figures.

Do you know of an example document (particularly the source) that
demonstrates these features in sphinx, so I can get the hang of them?
It doesn't have to be a Darcs mockup -- some other project's user
documentation would do.