-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
manpage and html builders: same rst file, different output #9430
Comments
A configuration value to optionally skip printing the description of a command as a subtitle when generating a manpage. This commit addresses issue sphinx-doc#9430 Signed-off-by: Harumi Kuno <[email protected]>
A configuration value to optionally skip printing the description of a command as a subtitle when generating a manpage. This commit addresses sphinx-doc#9430 Signed-off-by: Harumi Kuno <[email protected]>
I think I should perhaps have entered this as a bug instead of as an enhancement request. |
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:/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:
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:
|
Don't print the description of a command as a subtitle when generating a manpage if the description is empty. This commit addresses sphinx-doc#9430 Signed-off-by: Harumi Kuno <[email protected]>
Don't print the description of a command as a subtitle when generating a manpage if the description is empty. This commit addresses sphinx-doc#9430 Signed-off-by: Harumi Kuno <[email protected]>
If the supplied command description is empty, do not print command - description This commit addresses sphinx-doc#9430 Signed-off-by: Harumi Kuno <[email protected]>
Don't print the description of a command as a subtitle when generating a manpage if the description is empty. This commit addresses sphinx-doc#9430 Signed-off-by: Harumi Kuno <[email protected]>
Don't print the description of a command as a subtitle when generating a manpage if the description is empty. This commit addresses sphinx-doc#9430 Signed-off-by: Harumi Kuno <[email protected]>
@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.) |
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. |
Thank you, and welcome back! |
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:/open-mpi/). Here is a simple example: https:/jsquyres/ompi-sphinx-dist/blob/main/docs/src/ompi-man/man3/MPI_Abort.3.rst
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.
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
The text was updated successfully, but these errors were encountered: