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

[Patrick Williams]

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.

> So, I'd be happy going the sphinx/restructured text way for skiboot and
> maybe even the broader documentation efforts. It's a single toolchain,
> rather well known, well maintained, easy to write in (wiki like syntax).

"wiki like" ... Wiki-format is Markdown.

-- 
Patrick Williams
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <http://lists.ozlabs.org/pipermail/openpower-firmware/attachments/20160713/0c49a8e5/attachment-0001.sig>