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 <[email protected]> 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 > > [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/ > -- > coreboot mailing list: [email protected] > https://mail.coreboot.org/mailman/listinfo/coreboot -- http://marcjonesconsulting.com
-- coreboot mailing list: [email protected] https://mail.coreboot.org/mailman/listinfo/coreboot
