-----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----- _______________________________________________ qa-devel mailing list qa-devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/qa-devel