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
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@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.
- 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@coreboot.org https://www.coreboot.org/mailman/listinfo/coreboot
-
Martin Roth -
Paul Menzel