-----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/)