[darcs-users] Separating the user manual and code

Max Battcher me at worldmaker.net
Wed Oct 22 05:56:14 UTC 2008


Trent W. Buck wrote:
> My strong personal preference is for reST, because it has a relatively
> pleasant source markup, is relatively featureful for a lightweight
> markup language, has a --strict mode, and generates pretty good HTML
> and
> (with the new rst2pdf) PDF output.  I'm still concerned with its
> scalability (document class "book" instead of "article"), but there's a
> recent spin-off called Sphinx which might address that.
> 
> References:
> 
>   http://docutils.sf.net/
>   http://code.google.com/p/rst2pdf/
>   http://sphinx.pocoo.org/
> 
> This would also give coloured code snippets, which some people might
> conceivably care about.


This gets a big +1 from me.  I've been using reStructuredText for a while
now (most of the blog posts on my website are written in reST, particularly
when I post about darcs actually), but some of my enthusiasm for it comes
from the number of Python projects I work on, so I'm not sure how much
interest there is here.  First of all, Sphinx is awesome.  If you haven't
seen my work in progress documentation for "Darcsforge", it's built with
Sphinx:

http://repos.worldmaker.net/darcsforge/main/docs/.build/html/index.html

For every page there you can click "View Source" on the side-bar and see the
reStructuredText source of the page (which I think generally works well as
readable "ASCII" when unformatted).  Sphinx generates Tables of Contents and
all of the navigation and indices, including the "quick search".  Sphinx
uses Pygments for syntax highlighting (and I've contributed a lexer for
parsing Darcs patches, by the way).

Sphinx creates a simple make file and generating output is as simple as
"make html" or "make pdf" (also support for Windows HTML Help for a more
"native" documentation experience in Windows) in the documents directory.

Here's a couple more (close-to-hand) examples of Sphinx-based documentation:

http://docs.djangoproject.com/en/dev/
http://docs.python.org/

Here's a .pdf set from the Python documentation, which I think looks great:

http://docs.python.org/ftp/python/doc/current/python-docs-pdf-letter.zip

Finally, here's a great general resource on reStructuredText:

http://rst2a.com/

It's an "evangelism" website with tools that let you play with
reStructuredText formatting and offer some gentle Quick Start learning
tools.

--
--Max Battcher--
http://worldmaker.net



More information about the darcs-users mailing list