Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Subject: Do not print empty description for manpage builder
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
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:/open-mpi/). Here is a simple example: https:/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:/open-mpi/ompi/tree/master/ompi/mpi/man/man3
If rst/conf.py contains the following:
... then the generated man page will look like this:
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
Relates