[OpenPower-Firmware] [Skiboot] Sphinx/ReSructured Text (RST) for skiboot docs (maybe others?)

[Nathan Whitehorn]

On 07/13/16 09:15, Patrick Williams wrote:
> On Wed, Jul 13, 2016 at 09:14:28AM +1000, Stewart Smith wrote:
>> Hi all,
>>
>> So, it seems that the Linux kernel and devicetree.org are heading (or
>> have headed) to use RST (ReStructured Text) and the sphinx
>> infrastructure around it.
>>
>> For skiboot we currently have:
>> - text files in doc/
>>
>> and for broader OpenPower firmware, we have:
>> - some markdown
>> - some text files
>> - some PDFs
>> - ???
> What are the advantages of RST over Markdown?  I would tend to think we
> should commonize on Markdown since they are automatically rendered in
> Github.
>
> Jeremy Kerr has some scripting he was working on to generate PDFs from
> the Markdown we use for documentation in openBMC.
>
> The PDFs are there only because we have people that wrote Word documents
> and then 'published' them as PDFs out to Github.  It would be great if
> those could be transitioned over to Markdown too.
>
GitHub also automatically renders RST.
-Nathan