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 _______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
