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/
Jonathan,
Thanks, I think this looks great. I hadn't had a chance to see it since the patches landed. For those that haven't, you should go check out https://doc.coreboot.org/ .
Marc
On Mon, Apr 23, 2018 at 7:04 AM Jonathan Neuschäfer j.neuschaefer@gmx.net wrote:
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
[6]: http://commonmark.org/
coreboot mailing list: coreboot@coreboot.org https://mail.coreboot.org/mailman/listinfo/coreboot
-
Jonathan Neuschäfer -
Marc Jones