<div dir="ltr">Jonathan, <div><br></div><div>Thanks, I think this looks great. I hadn't had a chance to see it since the patches landed. </div><div>For those that haven't, you should go check out <a href="https://doc.coreboot.org/">https://doc.coreboot.org/</a> .</div><div><br></div><div>Marc</div></div><br><div class="gmail_quote"><div dir="ltr">On Mon, Apr 23, 2018 at 7:04 AM Jonathan Neuschäfer <<a href="mailto:j.neuschaefer@gmx.net">j.neuschaefer@gmx.net</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hello coreboot community,<br>
<br>
recently, I tried to use Hugo view some documentation in HTML form, but<br>
I couldn't get it to work properly (some pages 404'd when they<br>
shouldn't). So I decided to look into using Sphinx[1] again.<br>
I configured[2] Sphinx and the recommonmark Markdown parser for our<br>
Documentation directory. The result can be viewed here:<br>
<br>
        <a href="https://neuschaefer.github.io/coreboot/" rel="noreferrer" target="_blank">https://neuschaefer.github.io/coreboot/</a><br>
<br>
<br>
Advantages of this approach:<br>
<br>
  - The "readthedocs" theme, which I used has a useful navigation<br>
    sidebar and allows full navigation without JavaScript (the search<br>
    box does need JavaScript, because the search is performed on the<br>
    client side.)<br>
  - The top-level table of contents (i.e. the navbar) is generated from<br>
    a markdown file[3] rather than a special configuration file[4].<br>
  - The necessary packages (sphinx-doc, python-recommonmark,<br>
    python-sphinx-rtd-theme) are available in Debian; but so is Hugo.<br>
<br>
Disadvantages:<br>
<br>
  - recommonmark does not support tables[5]. This is a limitation of the<br>
    CommonMark[6] dialect of Markdown. We'd have to use HTML tables<br>
    (<table>...</table>) instead.<br>
  - If we decide to switch <a href="https://coreboot.org/Documentation" rel="noreferrer" target="_blank">https://coreboot.org/Documentation</a> to Sphinx,<br>
    that would mean some work for the admins, like any other change in<br>
    infrastructure.<br>
<br>
Possible migration path:<br>
<br>
  - Merge Sphinx support<br>
  - Look how well it works, and decide whether it's worth keeping, or<br>
    drop it<br>
  - Switch <a href="https://coreboot.org/Documentation" rel="noreferrer" target="_blank">https://coreboot.org/Documentation</a> (or <a href="https://doc.coreboot.org/" rel="noreferrer" target="_blank">https://doc.coreboot.org/</a>?)<br>
    to Sphinx<br>
  - Remove hugo support<br>
<br>
<br>
Overall, I like this setup, and I'd like <a href="https://coreboot.org/Documentation" rel="noreferrer" target="_blank">https://coreboot.org/Documentation</a><br>
to switch to it, but it has a few limitations.<br>
<br>
I'd like to hear your opinions!<br>
<br>
<br>
Thanks,<br>
Jonathan Neuschäfer<br>
<br>
[1]: <a href="http://www.sphinx-doc.org/en/stable/" rel="noreferrer" target="_blank">http://www.sphinx-doc.org/en/stable/</a><br>
[2]: <a href="https://review.coreboot.org/#/c/coreboot/+/25787/" rel="noreferrer" target="_blank">https://review.coreboot.org/#/c/coreboot/+/25787/</a><br>
[3]: <a href="https://review.coreboot.org/#/c/coreboot/+/25787/1/Documentation/index.md" rel="noreferrer" target="_blank">https://review.coreboot.org/#/c/coreboot/+/25787/1/Documentation/index.md</a><br>
[4]: <a href="https://review.coreboot.org/cgit/coreboot.git/tree/util/hugo/config.toml#n30" rel="noreferrer" target="_blank">https://review.coreboot.org/cgit/coreboot.git/tree/util/hugo/config.toml#n30</a><br>
[5]: <a href="https://github.com/rtfd/recommonmark/issues/3" rel="noreferrer" target="_blank">https://github.com/rtfd/recommonmark/issues/3</a><br>
[6]: <a href="http://commonmark.org/" rel="noreferrer" target="_blank">http://commonmark.org/</a><br>
-- <br>
coreboot mailing list: <a href="mailto:coreboot@coreboot.org" target="_blank">coreboot@coreboot.org</a><br>
<a href="https://mail.coreboot.org/mailman/listinfo/coreboot" rel="noreferrer" target="_blank">https://mail.coreboot.org/mailman/listinfo/coreboot</a></blockquote></div>-- <br><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><a href="http://marcjonesconsulting.com">http://marcjonesconsulting.com</a></div></div>