Re: [PATCH] docs: generate manpage from README and HOWTO

[Jens Axboe <axboe@kernel.dk>]

On 3/2/22 8:22 AM, Vincent Fu wrote:
> 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.

That should most certainly be solvable.

> 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.

Definitely! I absolutely hate that we have duplicated documentation,
and having to ask people to update both when they submit changes is
definitely not idea.

I don't have a lot of time to look into this right now, but would
certainly entertain applying the patch if I know the submitter has done
the legwork on checking if things look good post the patch.

-- 
Jens Axboe