Documentation Tools

[Mike Ruckman]

On Thu, 30 Jan 2014 13:35:51 +1000
Nick Coghlan <ncoghlan at 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 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://lists.fedoraproject.org/pipermail/qa-devel/attachments/20140130/6513fa11/attachment.sig>