Hello coreboot community,
recently, I tried to use Hugo view some documentation in HTML form, but I couldn't get it to work properly (some pages 404'd when they shouldn't). So I decided to look into using Sphinx[1] again. I configured[2] Sphinx and the recommonmark Markdown parser for our Documentation directory. The result can be viewed here:
https://neuschaefer.github.io/coreboot/
Advantages of this approach:
- The "readthedocs" theme, which I used has a useful navigation sidebar and allows full navigation without JavaScript (the search box does need JavaScript, because the search is performed on the client side.) - The top-level table of contents (i.e. the navbar) is generated from a markdown file[3] rather than a special configuration file[4]. - The necessary packages (sphinx-doc, python-recommonmark, python-sphinx-rtd-theme) are available in Debian; but so is Hugo.
Disadvantages:
- recommonmark does not support tables[5]. This is a limitation of the CommonMark[6] dialect of Markdown. We'd have to use HTML tables (<table>...</table>) instead. - If we decide to switch https://coreboot.org/Documentation to Sphinx, that would mean some work for the admins, like any other change in infrastructure.
Possible migration path:
- Merge Sphinx support - Look how well it works, and decide whether it's worth keeping, or drop it - Switch https://coreboot.org/Documentation (or https://doc.coreboot.org/?) to Sphinx - Remove hugo support
Overall, I like this setup, and I'd like https://coreboot.org/Documentation to switch to it, but it has a few limitations.
I'd like to hear your opinions!
Thanks, Jonathan Neuschäfer
[1]: http://www.sphinx-doc.org/en/stable/ [2]: https://review.coreboot.org/#/c/coreboot/+/25787/ [3]: https://review.coreboot.org/#/c/coreboot/+/25787/1/Documentation/index.md [4]: https://review.coreboot.org/cgit/coreboot.git/tree/util/hugo/config.toml#n30 [5]: https://github.com/rtfd/recommonmark/issues/3 [6]: http://commonmark.org/