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

[Stewart Smith]

Patrick Williams <patrick at stwcx.xyz> writes:
> 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.

Generally it's a more complete toolchain, and it's a bit more standard
than markdown (which seems to have a few variants).

Sphinx can do things like:
- support translation of documentation (gettext style)
- heavily structured, multi file documents with links between (and
  between different sphinx documents)
- output into html,latex,manpage,texinfo
- be parsable in python, and existing toolchain supports extensions that
  can do all sorts of crazy things such as build+test code snippets
- relatively complete templating, enabling things like branding docs
  with OpenPOWER Foundation logos and the like

(and please do correct me if i'm wrong), but Markdown seems to be a bit
more geared towards a single page/document of docs rather than more book
like volumes.

-- 
Stewart Smith
OPAL Architect, IBM.