Love it and thank you for taking on the work to modernise flashrom documentation Thomas! This is long overdue.
Kindest regards, Edward. On Tue, 14 Feb 2023 at 04:27, Thomas Heijligen <s...@posteo.de> wrote: > 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/ > _______________________________________________ > flashrom mailing list -- flashrom@flashrom.org > To unsubscribe send an email to flashrom-le...@flashrom.org >
_______________________________________________ flashrom mailing list -- flashrom@flashrom.org To unsubscribe send an email to flashrom-le...@flashrom.org
