manpage and html builders: same rst file, different output

[hkuno]

Is your feature request related to a problem? Please describe.
Many well-established software library projects that predate RST have a large number of existing *roff-style man pages.
Such projects often have both online documentation on the web and also man pages for use on linux operating systems.
When such packages choose to switch their man pages from nroff to RST, they may want to use a single set of RST files as source to produce both their online documentation (html files) and also their linux man pages (nroff files).

However, the manpage.py builder currently always adds a subtitle with a description of the command that is provided as input to config and the html builders do not do this.

This means that the RST author currently has to produce different RST source files for the manpage and the html builders,
because if the RST file contains a description of the command then that description will appear twice in the generated man page, and if the RST file does NOT contain a description of the command, then there will be no description in the generated html file.

For example, @jsquyres and I would like to generate both groff files and also html files from a single set of rst man page files for the Open-MPI project (https://github.com/open-mpi/). Here is a simple example: https://github.com/jsquyres/ompi-sphinx-dist/blob/main/docs/src/ompi-man/man3/MPI_Abort.3.rst

If rst/conf.py contains the following:

man_pages=[("ompi/mpi/man/man3/MPI_Abort.3","MPI_Abort", "(from conf.py) Terminates MPI execution environment","",3)]

... then the generated man page will look like this:

MPI_ABORT(3)                            Open MPI                            MPI_ABORT(3)

NAME
       MPI_Abort - (from conf.py) Terminates MPI execution environment

       MPI_Abort - Terminates MPI execution environment.

SYNTAX
   C Syntax
          #include <mpi.h>
          int MPI_Abort(MPI_Comm comm, int errorcode)
...

If we omit the "MPI_Abort - Terminates MPI execution environment." line from the RST file, then the generated html page will lose that command description.

Describe the solution you'd like
Could sphinx-build allow users to direct the manpage builder to not print out the descriptive subtitle by submitting an empty description string? For example, see submitted PR #9594.

Describe alternatives you've considered
We initially proposed requesting that sphinx-build include a configuration option to not add the descriptive subtitle to the generated man pages, but we closed that PR #9431 because the solution in PR #9594 seems cleaner.

We considered writing a script to parse our rst files and generate separate sets of rst files for use by the manpage builder versus the html file builder. This would mean we'd have two separate sets of RST files.

We also considered writing a script to edit the generated groff files to remove the descriptive subtitles added by the sphinx manpage builder. We would need to run this script every time we use sphinx-build.

Additional context

• Submitted PR: let user skip printing command description #9594
• Closed PR: Add man_skip_desc_subtitle option #9431

[hkuno]

I think I should perhaps have entered this as a bug instead of as an enhancement request.

[tk0miya]

Could you share an example of the source reST file? I'd like to know how you wrote own descriptions of commands.

[hkuno]

Could you share an example of the source reST file? I'd like to know how you wrote own descriptions of commands.

@tk0miya : Sure! Thank you very much for your help. Here is a simple example: https://github.com/jsquyres/ompi-sphinx-dist/blob/main/docs/src/ompi-man/man3/MPI_Abort.3.rst

I've thought about this issue more, in the meantime, and I'm thinking that perhaps I should submit a different solution, that if the user specifies an empty description, then skip the generation of the description subtitle.

For example:

man_pages=[("ompi/mpi/man/man3/MPI_Abort.3","MPI_Abort", "","",3)]

Currently, if someone were to do that, then sphinx would generate a subtitle that contains the operation name, a dash, and then an empty string. For example, like this:

MPI_ABORT(3)                            Open MPI                            MPI_ABORT(3)

NAME
       MPI_Abort - 

[hkuno]

@tk0miya -- I have updated the description and also the title of the issue. Having done so, I realized that actually, I think this issue is a bug, as opposed to an enhancement request. Could I ask you to please change the label of this issue from "enhancement" to "bug"? (Adding @jsquyres to keep him in the loop.)

[tk0miya]

I'm sorry for I could not reply for long. I'm back now.

Thank you for your explanation. I perfectly understand your problem. Indeed, we need to write the title and subtitle to the reST file if we'd like to publish the document as both manpage and HTML. I can't classify this as a bug or enhancement. But I can say this is a required improvement.

[hkuno]

Thank you, and welcome back!

[jsquyres]

@tk0miya Can you approve the CI workflows on #9594? Thank you!