[darcs-users] Separating the user manual and code

[Max Battcher]

Trent W. Buck wrote:
> 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.

Interesting...  Sphinx's aim is not to be an API documentation tool 
(although it has extensions to do that, because it almost has to due to 
Python auto-API documentation tools being something like a dime a 
dozen).  Perhaps what is throwing you off is the idea that Sphinx uses 
API-based "buckets" for cross-references.  The idea is _not_ to focus on 
writing API documentation, but that API things are commonly related to 
user concepts.

I would say it's something of the opposite, but perhaps more useful, 
approach from the literate haskell: the literate haskell seeks to embed 
the documentation in the context of the source code and the Sphinx 
technique is generally to embed ties to the source code in the context 
of the user documentation.  Some of that comes from the Python-world 
fact that often user interface and API are cross-bound, but I don't see 
it being entirely useless to darcs.

For an example of the Sphinx approach here:

You can mark any section of the documentation, maybe its a page, maybe 
its a just a paragraph, as "having something to do with the module 
Darcs.Internal.Wobbly"...  It doesn't have to be haddock-style API 
documentation and in fact philosophically Sphinx frowns on that in user 
documentation (while providing tools to do auto-API documentation for 
developer documentation).  A user reading through the manual (module 
directives don't have much output markup) may not notice that they are 
reading about anything related to a particular code module, but that tag 
(directive) becomes useful when someone is searching the module index 
wondering something like "what is the user need/impact of 
Darcs.Internal.Wobbly" in the user documentation.  It also serves as an 
easy and semantic cross-reference to write in other areas 
:module:`~Darcs.Internal.Wobbly` (the tilde elides the Darcs.Internal, 
outputting only Wobbly in the hyperlink) and when someone is reading it 
in ASCII form they get some information on what the link has to do with 
(referencing a module).

So like I said, it can be somewhat usefully the opposite of the current 
literate haskell approach...  rather than focus on recording the user 
impact in the source, it can be useful to record the code impact on the 
user documentation.

> 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.

I mentioned it in a previous post, but I've got Sphinx-based 
documentation for my "Darcsforge" project:

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

The source code for each page is linked in the sidebar of the HTML 
output, or you could:

darcs get http://repos.worldmaker.net/darcsforge/main/

The documentation is under ./docs and if you install Sphinx you can 
build it yourself with a simple make html.  There's only one page there 
I consider "API documentation", even though most of my cross-references 
fall into the "API buckets".

I think that the Python and Django documentation sites are decent 
examples as well, although perhaps not "better" because both are 
frameworks where arguably the user documentation still looks like API 
documentation.

I could trawl through the other Projects that use Sphinx and try to find 
better examples...  http://sphinx.pocoo.org/examples.html

Well, this email got larger than I intended, hopefully there are 
interesting seeds here,

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