From j.neuschaefer@gmx.net Mon Apr 23 15:08:28 2018
From: Jonathan =?utf-8?q?Neusch=C3=A4fer?= <j.neuschaefer@gmx.net>
To: coreboot@coreboot.org
Subject: [coreboot] [RFC] Building the documentation with Sphinx
Date: Mon, 23 Apr 2018 15:03:25 +0200
Message-ID: <20180423130325.GA18452@latitude>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="===============8870509924732549710=="

--===============8870509924732549710==
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable

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=C3=A4fer

[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/

--===============8870509924732549710==
Content-Type: application/pgp-signature
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="signature.asc"
MIME-Version: 1.0

LS0tLS1CRUdJTiBQR1AgU0lHTkFUVVJFLS0tLS0KVmVyc2lvbjogR251UEcgdjEKCmlRSWNCQUFC
QWdBR0JRSmEzZG1PQUFvSkVBZ3dSSnFPODEvYlZjNFFBSW5FS2lLU0x6UlFBamJsWk0wMEdDYlYK
NGJNRkI5NnBKaTNjWnc2N3NtUm1FWTBUbHNPQTdVVHZSK2ZwWnJwQ0VSemJZSmk2R3ZMZ0taeE5x
UlJoWFg5bAovVUFHa1p0alB3TU1XZFI1K0xjYTlGVVZSSHN2UmgvNUZRaVJ6dGZBYmhLeFgxSEda
VjZ0U3ZwWU43NDYxK2ExCmdMem5DM3RTb05RYjV3dG5WZk80WHk2N1ExT2tZdnJlcHFvTFRhNktz
eTdWRWJuN3ZKc0wyQmVxQWg3MDV2eWQKZnF6Q0lmUjYzZC8waFR5VHBFakxDckJVTGhQcFVRS3Bw
YlJ5MEYvRVRRRnZVRzl2a2k4NDRTMUExV3ZkOURXOApSbEFLZHFESWFrNmRLbUlEekpoemduVms5
R1ArODg1ZTNpMzZ3VzRkdzRreXRxNE1tcURDcnMwVlpYV2J4VWtnCk1YQUt4Zmp4V3Y3enpvUDFm
eElrZVA3SUsvMWZBaHdxTHcySk16Z1VVeE1POHlra2gvVEpoVTdwWHlON2hZYlkKTG85ZWVaY0dC
K09INlBPNHRHTTJEbTU1RTBuTS9GcmFZeHlGYVBOdWtCVCtuTkdBQ2UvRUQrRFFLNVJTSlJpNwpG
cXE4OWVtTjhBWjdwSXhheVF3cjRBMmtTOXBHT0gzcjFDTnA4c2JXSGdKWXlhc3hGOTFSSHFzZDJC
eFMvUHMvClBXWjduVVVFVjJXREpGMW9mR1ZaWE55eWp6Q3JvV1VRQzgwUTlOL2FrN242MVBtejNj
RGxtZ2piSnJJb1RlQVgKRVRod3pMYlNCR1lVYW9UaTNlQnJycFZaZHluNG9mQ0NFYVRsSUtrMXNI
a3FVaGNPZ1JMMjZMRFpkTDJXUjZWNQpsZmlod2ViNjJQVnQzQ2hvMEpORwo9Tm11TAotLS0tLUVO
RCBQR1AgU0lHTkFUVVJFLS0tLS0K

--===============8870509924732549710==--