On Wed, Mar 2, 2022 at 9:28 AM Vincent Fu <vincent.fu@xxxxxxxxxxx> wrote: > > > -----Original Message----- > > From: Vincent Fu > > Sent: Wednesday, March 2, 2022 10:22 AM > > To: fio@xxxxxxxxxxxxxxx; axboe@xxxxxxxxx; martin.steigerwald@xxxxxxxxx; > > sandeen@xxxxxxxxxx > > Cc: Vincent Fu <vincent.fu@xxxxxxxxxxx> > > Subject: [PATCH] docs: generate manpage from README and HOWTO > > > > We have a longstanding problem where fio documentation updates must be > > made to both the HOWTO and manpage. > > > > Here is a solution that generates a manpage from the README and HOWTO > > using Sphinx. > > > > The downside to being able to maintain only one version of the > > documentation is that this will cause a bit of trouble for those who package > > fio and users building fio without Sphinx support will no longer have a > > manpage. > > > > Does this seem like a reasonable tradeoff? If so, I will follow up with patches > > to remove the original manpage and update the Sphinx-generated manpage > > to have the standard NAME, SYNOPSIS, DESCRIPTION, etc layout. > > > > Oops, this was intended to be a RFC. I'm fairly green in linux so I'm not sure about the Sphinx implications, but single-sourcing the HOWTO/manpage would be really nice. Also, the documentation for command-line options is actually currently triple-sourced (HOWTO.rst, fio.1, and options.c). It would also be nice (not asking for now, just wishing for someday) if all of the options documentation could be single-sourced, likely from options.c.
