[coreboot] [RFC] Building the documentation with Sphinx

[Jonathan Neuschäfer]

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/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://mail.coreboot.org/pipermail/coreboot/attachments/20180423/40a3da71/attachment.asc>