Thanks, I think this looks great. I hadn't had a chance to see it since the
For those that haven't, you should go check out
On Mon, Apr 23, 2018 at 7:04 AM Jonathan Neuschäfer <j.neuschaefer(a)gmx.net>
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 again.
I configured Sphinx and the recommonmark Markdown parser for our
Documentation directory. The result can be viewed here:
Advantages of this approach:
- The "readthedocs" theme, which I used has a useful navigation
- The top-level table of contents (i.e. the navbar) is generated from
a markdown file rather than a special configuration file.
- The necessary packages (sphinx-doc, python-recommonmark,
python-sphinx-rtd-theme) are available in Debian; but so is Hugo.
- recommonmark does not support tables. This is a limitation of the
CommonMark dialect of Markdown. We'd have to use HTML tables
- If we decide to switch https://coreboot.org/Documentation
that would mean some work for the admins, like any other change in
Possible migration path:
- Merge Sphinx support
- Look how well it works, and decide whether it's worth keeping, or
- Switch https://coreboot.org/Documentation
- Remove hugo support
Overall, I like this setup, and I'd like
to switch to it, but it has a few limitations.
I'd like to hear your opinions!
coreboot mailing list: coreboot(a)coreboot.org