[coreboot] Adapting Linux kernel documentation setup with Sphinx and reStructuredText

[Martin Roth]

Zaolin has been working for a while on updating our documentation, and his
plan is to switch coreboot to using Hugo for our documentation manager.[1]
 Hugo supports various different markup languages, including markdown,
html, RestructuredText, and AsciiDoc. [2]

I meant to send the list an email a while back about doing this, but got
sidetracked with other projects.  It's just been picked back up, so if
anyone has any thoughts, please feel free to comment, either here or in his
patches.  [3] [4]

We're going to try to switch away from the wiki for our documentation.  The
wiki is great for some things, but not so good for other things.  The
thought is that if we keep the documentation in the coreboot tree, in an
accessible format, people will be able to contribute to it more easily, and
it will hopefully stay more up-to-date.  The plan is to move some of the
documentation out of the wiki into the Documentation folder and adding new
documentation shortly.

And, as always, any documentation contributions would be greatly
appreciated. [5]

Martin

[1] https://gohugo.io/
[2] https://gohugo.io/content/supported-formats
[3] https://review.coreboot.org/#/c/16853/
[4] https://review.coreboot.org/#/c/16787/
[5] Please.

On Mon, Oct 3, 2016 at 1:56 AM, Paul Menzel via coreboot <
coreboot at coreboot.org> wrote:

> Dear coreboot folks,
>
>
> The Linux kernel switched to Sphinx and reStructuredText [1] for its
> documentation [2][3][4].
>
> Would it make sense to also use that for coreboot? I would see the
> following benefits.
>
> 1. It’s easier to import code like drivers from the Linux kernel to
> coreboot.
> 2. Developers familiar with the Linux kernel have it easier to work on
> coreboot.
> 3. The coreboot project could import all improvements the Linux kernel
> documenation gets.
>
>
> Thanks,
>
> Paul
>
>
> [1] https://en.wikipedia.org/wiki/ReStructuredText
> [2] https://static.lwn.net/kerneldoc/index.html
> [3] https://lwn.net/Articles/692704/
>     "Kernel documentation with Sphinx, part 1: how we got here"
> [4] https://lwn.net/Articles/692705/
>     "Kernel documentation with Sphinx, part 2: how it works
> --
> coreboot mailing list: coreboot at coreboot.org
> https://www.coreboot.org/mailman/listinfo/coreboot
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.coreboot.org/pipermail/coreboot/attachments/20161003/44edbf40/attachment.html>