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