[Buildbot-devel] Buildbot documentation in RST/Sphinx

[Simon Kennedy]

On 19/03/2011 17:08, Dustin J. Mitchell wrote:
> On Sat, Mar 19, 2011 at 6:37 AM, Simon Kennedy<sdk at sffjunkie.co.uk>  wrote:
>> When I was starting to read the buildbot docs it felt like I was
>> spending more time changing pages than reading the text and so in order
>
> I'm sure you've noticed that the documentation is also available as a
> single page, right?

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.

>
>> to speed up my reading I started to create the docs in RST/Sphinx with
>> some of the sections joined together.
>
> This is great - I had been considering doing so for a while now:
>    http://trac.buildbot.net/ticket/189
> Lukas merged a copy of Thomas's tutorial during the PyCon sprints this
> week, and that is in RST, so I think it makes sense to convert all the
> way.

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

>
>> It's the docs from version 0.8.1
>
> Unfortunately, this doesn't do much good in terms of merging to trunk
> - most likely hand-applying all docs changes since 0.8.1 would be more
> difficult than simply reformatting the docs on master.
>
> Assuming you used some scripts to do this, could you re-run them on
> the master documentation, format it to your liking, and send along a
> pull request?

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

Regards
Simon Kennedy