On Thu, 30 Jan 2014 13:35:51 +1000
Nick Coghlan <ncoghlan(a)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