manpage and documentation - flashrom

14 Feb 2023


      Hi flashromers,
For all the time I'm now working on flashrom I've avoided to touch the
man-page. The reason: it is written in plain groff (the manpage
format), which is, IMO, neither great to read in source nor makes it
fun to edit.
Nowadays there are a lot of tools for converting a source readable
format like md or rst into groff / man-pages. So I've played around
with some and found a solution with `Sphinx`[0] that might fit flashrom
well. Sphinx is well known in the Open Source Community for project
documentation. Coreboot, the Linux kernel and many other projects are
using it already. So it is time tested and nothing really new. Beside
rendering to html sides, sphinx is also capable to render
groff/manpages which is quite nice.
My reason for choosing sphinx over other tools was:
- It is known to many people
- reStructuredText is easy to read and write
- It can produce groff/manpages *and* html without
plugins/extensions/quirks
- It is, like our meson based build system, written in python. So it
runs where the build system runs and has no additional software stack
like nodejs or ruby on rails
- It is extendable to our needs (e.g. generate documentation from data
with python)
The conversion of the manpage from groff to sphinx/rst can be found
here: https://review.coreboot.org/c/flashrom/+/72619
Going forward I would also like to suggest integrating the existing
documentation of the Wiki to Sphinx (flashrom source / Gerrit) and
supersede the current homepage with it.
What do you think about this?
-- Thomas
[0] https://www.sphinx-doc.org/en/master/