[Buildbot-devel] Buildbot documentation in RST/Sphinx

[Dustin J. Mitchell]

On Sat, Mar 19, 2011 at 1:25 PM, Simon Kennedy <sdk at sffjunkie.co.uk> wrote:
> Yes, I did see that. However my brain just can't quite process the
> information when it's presented like that. I get distracted with small
> things like trying to grab hold of the scroll bar as it's so small in
> long docs, or work out where I am in the doc. It's sort an allergy. And
> so I discount all documentation as a single page without looking as I
> feel like I would be fighting the docs not absorbing the information.

I'll refrain from sugggesting two-finger scrolling ;)

I like the long format because I can use "find" to find exactly the
parameter I need without skimming the table of contents, but at the
end of the day I won't argue that it's inconvenient, and Sphinx's
built-in JavaScript-based search is much better.

> Yes, RST+Sphinx is a nice combination. In the future all docs will be
> made that way :-J

Jacob Kaplan-Moss's PyCon talk certainly suggested that!  Also, it's
the only format accepted by readthedocs.com.

> Unfortunately it was all done by hand. I'll look at the best way of
> updating the docs and let you know.

The other devs are too busy working on the code at the moment to make
the transition, so the ticket is assigned to the 0.8.5 milestone, but
if you can translate it in the next month or so, we can even get it
into 0.8.4.

Dustin