Documentation Tools

[Nick Coghlan]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 01/29/2014 02:09 AM, Mike Ruckman wrote:
> I've posted a comparison between Sphinx and Dexy [1] - as well as 
> updated the phabricator ticket [2]. The tools are pretty similar
> in what they can produce, so it really comes down to what people
> are comfortable with. The learning curve for Dexy isn't steep, and
> I think it's just enough easier to use compared to Sphinx for our
> purposes.
> 
> I wasn't able to find air-tight reasoning for one over the other
> for qa-devel work - but found dexy a bit easier to use and
> template. Source for both tutorials can be found on my bitbucket
> profile [3].

- From my perspective, the killer feature of using Sphinx for a new
project isn't Sphinx itself, but ReadTheDocs: https://readthedocs.org/

Sure, you *can* still host your own docs if you really want to, but
RTFD means you can just set up a POST hook on your repo and go.
Building draft docs from a development branch or a forked repo is also
trivial (handy if you're wanting to make it easy for people to review
a proposed theme change, or other major docs refactor without needing
to build the docs locally).

The other interesting Sphinx feature I find invaluable when working on
CPython, Beaker and my own projects is the flexible autoupdating cross
references (including to other projects through the intersphinx
extension). Dexy's section-titles-only cross linking capabilities seem
like a relatively poor substitute
(http://dexy.github.io/dexy-user-guide/#_links_to_pages_and_sections),
suffering from the limitations imposed by its agnosticism regarding
input formats.

For example, Sphinx doesn't care if different sections use the same
title, or if the exact section titles change, so long as they use a
unique and consistent reference label. Customising the text used for a
cross reference is also trivial (:ref:`this is a cross reference
<to-this-label>`). A lot of things are also inherently labelled, so
you can do :class:`name` or :func:`name` (with Python, C, C++,
JavaScript and REST domains currently supported for that). The
glossary feature is also excellent in being able to easily hyperlink
term definitions.

More details here:
http://sphinx-doc.org/markup/inline.html#cross-referencing-syntax

Cheers,
Nick.

- -- 
Nick Coghlan
Red Hat Hosted & Shared Services
Software Engineering & Development, Brisbane

Testing Solutions Team Lead
Beaker Development Lead (http://beaker-project.org/)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJS6ciRAAoJEHEkJo9fMO/LgdYH/jifYHkhtlP+jtTbkumBoTw4
vbBhRhBJTTEsSiLHyrWL7X0o/hsr0IwG7+Yxvg7VB9kfpiDZcGy1a7PkM3heTSLf
NnQN8Xf+wysi6HR74lMMNLknfW1H5ukqLS85v8xEE/mxyq0iZQgkab2EIUePIev2
CUdkEU1W8SzX1c5+A2LCk+tLXdnpvIyJE95zKEI3PNwXAEkkUrVSuIp/56R+TFVj
t6oz27nsoJNnshckwmQn8/kLqiYGKxLf2KAtzIkXcdKOX0q9kWiASq1ZdnEuVjMF
Miq16EIrAb55Djw8N5yAy2mauEat+ZeYWcz5QP35yvGltaJe2GOMDqvebU9qcIg=
=olKc
-----END PGP SIGNATURE-----