Adapting Linux kernel documentation setup with Sphinx and reStructuredText

[Paul Menzel]

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

[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 <
[e-mail]> 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: [e-mail]
> https://www.coreboot.org/mailman/listinfo/coreboot