let user skip printing command description

[hkuno]

Subject: let user skip printing command description

Update manpage builder to skip printing the description of a command as a subtitle if the supplied description is blank.
This commit addresses #9430

Feature or Bugfix

• Bugfix

Purpose

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 . Some examples of the original nroff files are here: https://github.com/open-mpi/ompi/tree/master/ompi/mpi/man/man3

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.

This PR would make it possible for us to use sphinx-build to produce both HTML and manpage files from a single set of RST files.

Detail

• manpage and html builders: same rst file, different output #9430

Relates

• Please see issue manpage and html builders: same rst file, different output #9430

[tk0miya]

LGTM! Could you update the document of man_page? Testcase is also needed for this.

[hkuno]

LGTM! Could you update the document of man_page? Testcase is also needed for this.

I'll be happy to do that!
I have updated the doc/usage/configuration.rst file, which made me realize that it would be more consistent to omit the entire NAME section if the description is an empty string. Doing that matches how entering an empty string for authors omits the AUTHORS section, so I also made that change.

Regarding the testcase, do you mean add a new testcase to test_build_manpage.py?

[tk0miya]

Now I added a testcase directly.

[tk0miya]

Merged. Thank you for your contribution!