[coreboot] [RFC] Building the documentation with Sphinx

[Marc Jones]

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 at 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 at coreboot.org
> https://mail.coreboot.org/mailman/listinfo/coreboot

-- 
http://marcjonesconsulting.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/coreboot/attachments/20180510/61d55c0d/attachment.html>