[darcs-users] Sphinx or reST (for user manual)?
Trent W. Buck
trentbuck at gmail.com
Wed Oct 29 01:40:59 UTC 2008
Mark Stosberg <mark at summersault.com> writes:
>> >>> darcs get http://repos.worldmaker.net/darcs/sphinx/
> I did notice some of the drawbacks mentioned:
> - an extra "make" command beyond the top-level one
This is easily fixable with some changes to GNUmakefile that I posted
> - no single page output (that I noticed)
I'm not sure how to address this yet (since obviously the toctree
directive breaks plain rst2html).
> - no PDF output (currently)
$(MAKE) -C doc/manual latex
$(MAKE) -C doc/manual/_build/latex all-pdf
But this still requires sphinx and latex, which IMO is suboptimal.
> The output was attractive and functional.
One thing I don't like about the default output is that the menu is
physically located at the top of the file, so tty users get a few lines
of navigation junk before the "real" document. Cf. wikipedia articles
for how I prefer it -- all the navigation is at the end, and then
floated to the top via CSS for GUI users.
I also don't like the way tty users get spammed with ¶'s in headings,
which are hidden via CSS for GUI users.
I assume both of these are trivial to fix, but I've been wrong about
that before -- for example, the trac developers told me that I couldn't
move navigation junk to the bottom of their pages without completely
rewriting their templating code.
More information about the darcs-users