[darcs-users] Sphinx or reST (for user manual)?

[Max Battcher]

Trent W. Buck wrote:
> On Tue, Oct 28, 2008 at 03:55:00AM -0400, Max Battcher wrote:
>> * .. include becomes .. toctree
>>
>> * $Darcs_Version$ was replaced with |version| (an actual reST
>>   substitution), which is pulled from the configuration file.
> 
> This was my intention all along, though I'd like to make it explicit
> with this in GNUmakefile
> 
>     doc/manual/version.txt:
>     	echo ".. |version|: $(DARCS_VERSION)" >$@
>     clean:
>         rm doc/manual/version.txt
> 
> and then simply have darcs.txt do ".. include:: version.txt".

To amplify what I mentioned here...  Sphinx config files (and templates) 
have an in-built notion of version.  In my patches I replaced the 
mentions I found of version number with Sphinx's substitution.  I also 
made it so that the config slurps the version from a simple static text 
file (_conf/darcs_version).

>> Anyway, I prefer the Sphinx output of a full documentation website
>> over the single, giant HTML page
> 
> While I value the split-HTML output Sphinx can provide, I think the
> single-file HTML output of rst2html is far from useless.  For example,
> I prefer using grep(1) to non-standard search forms provided by
> websites, and it's much easier to just do M-x occur in my browser, or
> w3m -dump | grep if the document does not span multiple pages.

I didn't say that single-file HTML output is useless, I implied that 
it's usage is more rare and less natural for HTML (browsers don't like 
large HTML files and users seem to prefer tightly hyperlinked sets of 
pages).

I certainly believe that it should be possible to build a single-file 
HTML output with Sphinx, but I don't see as the big issue that you do.

> It appears that Sphinx does not do this; instead it generates an HTML
> file for each of the source documents, using a non-standard "toctree"
> directive to add links between them.  Actually it's slightly worse
> than that; sphinx-build will simply render ALL files (that have the
> appropriate extension) in the source tree, even if they aren't listed
> in a toctree.  This has the undesirable consequence of creating
> HACKING.html in the output tree, though HACKING.txt is only relevant
> to the technical writers (not readers).

sphinx-build only generates all source files in the case of HTML builds. 
  For Latex builds it follows the toctree strictly.  Even though 
HACKING.txt isn't a part of the user manual, we could theoretically have 
a "developer manual" built or linked out of the same manual build process.

>   rst2pdf has few dependencies: itself and reportlab (both pure
>   Python, thus portable), and optionally pyhyphen/wordaxe for
>   hyphenation (which includes a C module).

Sphinx has pluggable formatters and at the very least a rst2pdf build 
appears to be in the process of being built.

> However I'd like to take a different approach.  In short, rst2html is
> adequate for our needs except for one thing: it can't produce
> docbook-style split-HTML output.  Let's simply extend the stock HTML
> writer class (or possibly write a second HTML writer class) with this
> feature.  This means that
> 
>     1. other docutils users benefit;
>     2. the aforementioned toctree issues go away; and

This is exactly why Sphinx was built in the first place and re-building 
it seems a little extreme.  The Python community has debated and 
discussed this and Sphinx was built as a best practice tool from that 
debate.  The number of Python projects moving to Sphinx seems to imply 
that it works for the majority of reST-based projects.

(The toctree was built, among other reasons, to handle complex table of 
contents building via the subclusion of individual document table of 
contents into a larger table of contents, based on each document's own 
knowledge of their table of contents...  I certainly believe that 
building a special split-HTML tool would have to come up with answers to 
many of the same problems toctree was designed to solve...)

>     3. sphinx' api-oriented features don't get in our way.

I've already written a long email on why I think the "API-oriented" 
stuff is useful even to Darcs' user manual, but Sphinx makes it easy to 
turn off any that aren't needed and to extend any that don't quite fit 
Darcs' mental model.

> IMO split-HTML is an important feature, but not a critical one.

I absolutely disagree.  I think that split-HTML is critical for easy web 
access and bookmarking and smarter internet searches.  If an HTML output 
is less than critical it is single-file HTML, which serves a smaller 
more dedicated minority group than "the whole web philosophy" that 
split-HTML serves.  Plus, of the minority that prefer single-file HTML, 
many would be satisfied with single-file PDF or single-file CHM.

But that's just my opinion.

> - Having a second makefile is just wrong, see the ACM article
>   "Recursive Make Considered Harmful".  This isn't a problem with
>   sphinx itself, just sphinx-quickstart.  

It should be easy enough to merge it into the main make file...  If 
darcs moves to franchise/cabal for builds, we'd be at only a single 
makefile that way as well.

>   I don't like having non-documentation files in the doc/manual source
>   tree (particularly conf.py and _foo).  I have determined that this
>   can be obviated by a make rule like this:

I don't think this is a real issue.  Documents have .txt endings and the 
config file and resource directories are pretty obviously not 
documentation but useful to the documentation nonetheless.

> - sphinx-build ALWAYS emits SGR (ANSI) escape sequences.  Since I
>   often use dumb terminals and pure (non-tty) buffers, means I have to
>   go out of my way to make sphinx-build's output readable.

I've don't think I've seen anyone bring this up as an issue on the 
Sphinx mailing list.  I'll bring it up and maybe someone will write a 
patch to act more Darcs-like and attempt to discover if the current tty 
supports colors/rich output.

> - I don't like tweaking stylesheets and templates; it takes time both
>   up-front and for ongoing maintenance (so it works with newer
>   versions of sphinx), it tends to introduces accessibility issues,
>   and tends to introduce rendering issues with buggy (i.e. all)
>   browsers you forget to test with.
 >
>   And because Sphinx's default templates mention "modules", we'd have
>   to make and maintain at least minimal changes to make it "right" for
>   a user manual.

The module index can be turned off in the configuration.  I can see the 
case that modules make sense in the Darcs world as well (even in the 
user manual), as Haskell calls source files modules just as Python does. 
  Is there a problem in noting that darcs command add is from the module 
Darcs.Commands.Add?  As I've said before this can usefully replace some 
of Darcs' current reliance on literate haskell by reversing the flow of 
information (allowing developers to continue to get the answer to "what 
does the user manual have to say about module x?").

I think the default templates/stylesheets are fine for Darcs.  I would 
add the Darcs logo in appropriate spots (which already have template 
"holes") and maybe tweak the color scheme to better match the darcs 
homepage, but unless there is a UIX designer wanting to help out darcs 
by playing with the user manual output I don't see any real need to do 
much in the way of template/stylesheet tweaking.

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