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="===============0273160482534974278=="

--===============0273160482534974278==
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/

--===============0273160482534974278==
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

--===============0273160482534974278==--


From marcj303@gmail.com Thu May 10 19:07:59 2018
From: Marc Jones <marcj303@gmail.com>
To: coreboot@coreboot.org
Subject: Re: [coreboot] [RFC] Building the documentation with Sphinx
Date: Thu, 10 May 2018 17:03:14 +0000
Message-ID:
 <CALrs_3jAtb23V=t+4QaP7VtZNua6Bq7vALf17gMc8G5QHGjdFQ@mail.gmail.com>
In-Reply-To: <20180423130325.GA18452@latitude>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="===============4008290372518520891=="

--===============4008290372518520891==
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

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 <j.neuschaefer(a)gmx.net>
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: coreboot(a)coreboot.org
> https://mail.coreboot.org/mailman/listinfo/coreboot

-- 
http://marcjonesconsulting.com



--===============4008290372518520891==
Content-Type: text/html
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="attachment.htm"
MIME-Version: 1.0

PGRpdiBkaXI9Imx0ciI+Sm9uYXRoYW4swqA8ZGl2Pjxicj48L2Rpdj48ZGl2PlRoYW5rcywgSSB0
aGluayB0aGlzIGxvb2tzIGdyZWF0LiBJIGhhZG4mIzM5O3QgaGFkIGEgY2hhbmNlIHRvIHNlZSBp
dCBzaW5jZSB0aGUgcGF0Y2hlcyBsYW5kZWQuwqA8L2Rpdj48ZGl2PkZvciB0aG9zZSB0aGF0IGhh
dmVuJiMzOTt0LCB5b3Ugc2hvdWxkIGdvIGNoZWNrIG91dMKgPGEgaHJlZj0iaHR0cHM6Ly9kb2Mu
Y29yZWJvb3Qub3JnLyI+aHR0cHM6Ly9kb2MuY29yZWJvb3Qub3JnLzwvYT7CoC48L2Rpdj48ZGl2
Pjxicj48L2Rpdj48ZGl2Pk1hcmM8L2Rpdj48L2Rpdj48YnI+PGRpdiBjbGFzcz0iZ21haWxfcXVv
dGUiPjxkaXYgZGlyPSJsdHIiPk9uIE1vbiwgQXByIDIzLCAyMDE4IGF0IDc6MDQgQU0gSm9uYXRo
YW4gTmV1c2Now6RmZXIgJmx0OzxhIGhyZWY9Im1haWx0bzpqLm5ldXNjaGFlZmVyQGdteC5uZXQi
PmoubmV1c2NoYWVmZXJAZ214Lm5ldDwvYT4mZ3Q7IHdyb3RlOjxicj48L2Rpdj48YmxvY2txdW90
ZSBjbGFzcz0iZ21haWxfcXVvdGUiIHN0eWxlPSJtYXJnaW46MCAwIDAgLjhleDtib3JkZXItbGVm
dDoxcHggI2NjYyBzb2xpZDtwYWRkaW5nLWxlZnQ6MWV4Ij5IZWxsbyBjb3JlYm9vdCBjb21tdW5p
dHksPGJyPgo8YnI+CnJlY2VudGx5LCBJIHRyaWVkIHRvIHVzZSBIdWdvIHZpZXcgc29tZSBkb2N1
bWVudGF0aW9uIGluIEhUTUwgZm9ybSwgYnV0PGJyPgpJIGNvdWxkbiYjMzk7dCBnZXQgaXQgdG8g
d29yayBwcm9wZXJseSAoc29tZSBwYWdlcyA0MDQmIzM5O2Qgd2hlbiB0aGV5PGJyPgpzaG91bGRu
JiMzOTt0KS4gU28gSSBkZWNpZGVkIHRvIGxvb2sgaW50byB1c2luZyBTcGhpbnhbMV0gYWdhaW4u
PGJyPgpJIGNvbmZpZ3VyZWRbMl0gU3BoaW54IGFuZCB0aGUgcmVjb21tb25tYXJrIE1hcmtkb3du
IHBhcnNlciBmb3Igb3VyPGJyPgpEb2N1bWVudGF0aW9uIGRpcmVjdG9yeS4gVGhlIHJlc3VsdCBj
YW4gYmUgdmlld2VkIGhlcmU6PGJyPgo8YnI+CsKgIMKgIMKgIMKgIDxhIGhyZWY9Imh0dHBzOi8v
bmV1c2NoYWVmZXIuZ2l0aHViLmlvL2NvcmVib290LyIgcmVsPSJub3JlZmVycmVyIiB0YXJnZXQ9
Il9ibGFuayI+aHR0cHM6Ly9uZXVzY2hhZWZlci5naXRodWIuaW8vY29yZWJvb3QvPC9hPjxicj4K
PGJyPgo8YnI+CkFkdmFudGFnZXMgb2YgdGhpcyBhcHByb2FjaDo8YnI+Cjxicj4KwqAgLSBUaGUg
JnF1b3Q7cmVhZHRoZWRvY3MmcXVvdDsgdGhlbWUsIHdoaWNoIEkgdXNlZCBoYXMgYSB1c2VmdWwg
bmF2aWdhdGlvbjxicj4KwqAgwqAgc2lkZWJhciBhbmQgYWxsb3dzIGZ1bGwgbmF2aWdhdGlvbiB3
aXRob3V0IEphdmFTY3JpcHQgKHRoZSBzZWFyY2g8YnI+CsKgIMKgIGJveCBkb2VzIG5lZWQgSmF2
YVNjcmlwdCwgYmVjYXVzZSB0aGUgc2VhcmNoIGlzIHBlcmZvcm1lZCBvbiB0aGU8YnI+CsKgIMKg
IGNsaWVudCBzaWRlLik8YnI+CsKgIC0gVGhlIHRvcC1sZXZlbCB0YWJsZSBvZiBjb250ZW50cyAo
aS5lLiB0aGUgbmF2YmFyKSBpcyBnZW5lcmF0ZWQgZnJvbTxicj4KwqAgwqAgYSBtYXJrZG93biBm
aWxlWzNdIHJhdGhlciB0aGFuIGEgc3BlY2lhbCBjb25maWd1cmF0aW9uIGZpbGVbNF0uPGJyPgrC
oCAtIFRoZSBuZWNlc3NhcnkgcGFja2FnZXMgKHNwaGlueC1kb2MsIHB5dGhvbi1yZWNvbW1vbm1h
cmssPGJyPgrCoCDCoCBweXRob24tc3BoaW54LXJ0ZC10aGVtZSkgYXJlIGF2YWlsYWJsZSBpbiBE
ZWJpYW47IGJ1dCBzbyBpcyBIdWdvLjxicj4KPGJyPgpEaXNhZHZhbnRhZ2VzOjxicj4KPGJyPgrC
oCAtIHJlY29tbW9ubWFyayBkb2VzIG5vdCBzdXBwb3J0IHRhYmxlc1s1XS4gVGhpcyBpcyBhIGxp
bWl0YXRpb24gb2YgdGhlPGJyPgrCoCDCoCBDb21tb25NYXJrWzZdIGRpYWxlY3Qgb2YgTWFya2Rv
d24uIFdlJiMzOTtkIGhhdmUgdG8gdXNlIEhUTUwgdGFibGVzPGJyPgrCoCDCoCAoJmx0O3RhYmxl
Jmd0Oy4uLiZsdDsvdGFibGUmZ3Q7KSBpbnN0ZWFkLjxicj4KwqAgLSBJZiB3ZSBkZWNpZGUgdG8g
c3dpdGNoIDxhIGhyZWY9Imh0dHBzOi8vY29yZWJvb3Qub3JnL0RvY3VtZW50YXRpb24iIHJlbD0i
bm9yZWZlcnJlciIgdGFyZ2V0PSJfYmxhbmsiPmh0dHBzOi8vY29yZWJvb3Qub3JnL0RvY3VtZW50
YXRpb248L2E+IHRvIFNwaGlueCw8YnI+CsKgIMKgIHRoYXQgd291bGQgbWVhbiBzb21lIHdvcmsg
Zm9yIHRoZSBhZG1pbnMsIGxpa2UgYW55IG90aGVyIGNoYW5nZSBpbjxicj4KwqAgwqAgaW5mcmFz
dHJ1Y3R1cmUuPGJyPgo8YnI+ClBvc3NpYmxlIG1pZ3JhdGlvbiBwYXRoOjxicj4KPGJyPgrCoCAt
IE1lcmdlIFNwaGlueCBzdXBwb3J0PGJyPgrCoCAtIExvb2sgaG93IHdlbGwgaXQgd29ya3MsIGFu
ZCBkZWNpZGUgd2hldGhlciBpdCYjMzk7cyB3b3J0aCBrZWVwaW5nLCBvcjxicj4KwqAgwqAgZHJv
cCBpdDxicj4KwqAgLSBTd2l0Y2ggPGEgaHJlZj0iaHR0cHM6Ly9jb3JlYm9vdC5vcmcvRG9jdW1l
bnRhdGlvbiIgcmVsPSJub3JlZmVycmVyIiB0YXJnZXQ9Il9ibGFuayI+aHR0cHM6Ly9jb3JlYm9v
dC5vcmcvRG9jdW1lbnRhdGlvbjwvYT4gKG9yIDxhIGhyZWY9Imh0dHBzOi8vZG9jLmNvcmVib290
Lm9yZy8iIHJlbD0ibm9yZWZlcnJlciIgdGFyZ2V0PSJfYmxhbmsiPmh0dHBzOi8vZG9jLmNvcmVi
b290Lm9yZy88L2E+Pyk8YnI+CsKgIMKgIHRvIFNwaGlueDxicj4KwqAgLSBSZW1vdmUgaHVnbyBz
dXBwb3J0PGJyPgo8YnI+Cjxicj4KT3ZlcmFsbCwgSSBsaWtlIHRoaXMgc2V0dXAsIGFuZCBJJiMz
OTtkIGxpa2UgPGEgaHJlZj0iaHR0cHM6Ly9jb3JlYm9vdC5vcmcvRG9jdW1lbnRhdGlvbiIgcmVs
PSJub3JlZmVycmVyIiB0YXJnZXQ9Il9ibGFuayI+aHR0cHM6Ly9jb3JlYm9vdC5vcmcvRG9jdW1l
bnRhdGlvbjwvYT48YnI+CnRvIHN3aXRjaCB0byBpdCwgYnV0IGl0IGhhcyBhIGZldyBsaW1pdGF0
aW9ucy48YnI+Cjxicj4KSSYjMzk7ZCBsaWtlIHRvIGhlYXIgeW91ciBvcGluaW9ucyE8YnI+Cjxi
cj4KPGJyPgpUaGFua3MsPGJyPgpKb25hdGhhbiBOZXVzY2jDpGZlcjxicj4KPGJyPgpbMV06IDxh
IGhyZWY9Imh0dHA6Ly93d3cuc3BoaW54LWRvYy5vcmcvZW4vc3RhYmxlLyIgcmVsPSJub3JlZmVy
cmVyIiB0YXJnZXQ9Il9ibGFuayI+aHR0cDovL3d3dy5zcGhpbngtZG9jLm9yZy9lbi9zdGFibGUv
PC9hPjxicj4KWzJdOiA8YSBocmVmPSJodHRwczovL3Jldmlldy5jb3JlYm9vdC5vcmcvIy9jL2Nv
cmVib290LysvMjU3ODcvIiByZWw9Im5vcmVmZXJyZXIiIHRhcmdldD0iX2JsYW5rIj5odHRwczov
L3Jldmlldy5jb3JlYm9vdC5vcmcvIy9jL2NvcmVib290LysvMjU3ODcvPC9hPjxicj4KWzNdOiA8
YSBocmVmPSJodHRwczovL3Jldmlldy5jb3JlYm9vdC5vcmcvIy9jL2NvcmVib290LysvMjU3ODcv
MS9Eb2N1bWVudGF0aW9uL2luZGV4Lm1kIiByZWw9Im5vcmVmZXJyZXIiIHRhcmdldD0iX2JsYW5r
Ij5odHRwczovL3Jldmlldy5jb3JlYm9vdC5vcmcvIy9jL2NvcmVib290LysvMjU3ODcvMS9Eb2N1
bWVudGF0aW9uL2luZGV4Lm1kPC9hPjxicj4KWzRdOiA8YSBocmVmPSJodHRwczovL3Jldmlldy5j
b3JlYm9vdC5vcmcvY2dpdC9jb3JlYm9vdC5naXQvdHJlZS91dGlsL2h1Z28vY29uZmlnLnRvbWwj
bjMwIiByZWw9Im5vcmVmZXJyZXIiIHRhcmdldD0iX2JsYW5rIj5odHRwczovL3Jldmlldy5jb3Jl
Ym9vdC5vcmcvY2dpdC9jb3JlYm9vdC5naXQvdHJlZS91dGlsL2h1Z28vY29uZmlnLnRvbWwjbjMw
PC9hPjxicj4KWzVdOiA8YSBocmVmPSJodHRwczovL2dpdGh1Yi5jb20vcnRmZC9yZWNvbW1vbm1h
cmsvaXNzdWVzLzMiIHJlbD0ibm9yZWZlcnJlciIgdGFyZ2V0PSJfYmxhbmsiPmh0dHBzOi8vZ2l0
aHViLmNvbS9ydGZkL3JlY29tbW9ubWFyay9pc3N1ZXMvMzwvYT48YnI+Cls2XTogPGEgaHJlZj0i
aHR0cDovL2NvbW1vbm1hcmsub3JnLyIgcmVsPSJub3JlZmVycmVyIiB0YXJnZXQ9Il9ibGFuayI+
aHR0cDovL2NvbW1vbm1hcmsub3JnLzwvYT48YnI+Ci0tIDxicj4KY29yZWJvb3QgbWFpbGluZyBs
aXN0OiA8YSBocmVmPSJtYWlsdG86Y29yZWJvb3RAY29yZWJvb3Qub3JnIiB0YXJnZXQ9Il9ibGFu
ayI+Y29yZWJvb3RAY29yZWJvb3Qub3JnPC9hPjxicj4KPGEgaHJlZj0iaHR0cHM6Ly9tYWlsLmNv
cmVib290Lm9yZy9tYWlsbWFuL2xpc3RpbmZvL2NvcmVib290IiByZWw9Im5vcmVmZXJyZXIiIHRh
cmdldD0iX2JsYW5rIj5odHRwczovL21haWwuY29yZWJvb3Qub3JnL21haWxtYW4vbGlzdGluZm8v
Y29yZWJvb3Q8L2E+PC9ibG9ja3F1b3RlPjwvZGl2Pi0tIDxicj48ZGl2IGRpcj0ibHRyIiBjbGFz
cz0iZ21haWxfc2lnbmF0dXJlIiBkYXRhLXNtYXJ0bWFpbD0iZ21haWxfc2lnbmF0dXJlIj48ZGl2
IGRpcj0ibHRyIj48YSBocmVmPSJodHRwOi8vbWFyY2pvbmVzY29uc3VsdGluZy5jb20iPmh0dHA6
Ly9tYXJjam9uZXNjb25zdWx0aW5nLmNvbTwvYT48L2Rpdj48L2Rpdj4K

--===============4008290372518520891==--