On Thu, 30 Jan 2014 13:35:51 +1000 Nick Coghlan ncoghlan@redhat.com wrote:
<trimmed>
- 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).
I hadn't even considered RTD. I just assumed (bad of me, I know :P) that we'd be hosting our own docs. In a perfect world there'd be one place for documentation - but I don't know how likely that is. Thanks for bringing it up - hadn't occurred to me.
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.
That's a fair point. Something I didn't have was means for a complete comparison within a project. I merely liked the idea of multiple inputs because it easily incorporates projects in other languages that qa devel might use in the future - but that's far from a actual *reason* to pick it as the tool.
Oh, and nice to meet you Nick :)
// Roshi
<snip>
Cheers, Nick.
Nick Coghlan Red Hat Hosted & Shared Services Software Engineering & Development, Brisbane
Testing Solutions Team Lead Beaker Development Lead (http://beaker-project.org/)
I