man1: improve HTML formatting of man pages #5521
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Problem: the extra click to get to the actual man1 pages from readthedocs is annoying. Since most man page users already know what they want to look up, flatten out the section 1 index with commands in lexicographical order.
Problem: flux-alloc(1) mentions flux-proxy(1) without linking. Add the :man1:`flux-proxy` linkage.
Problem: flux-mini has been deprecated for some time, but still has a man page we have to maintain. Drop the man page.
Problem: flux-bulksubmit.rst includes its content from common/submit-bulksubmit.rst because it was shared with flux-mini.rst but flux-mini(1) is no more. Move that content into flux-bulksubmit.rst.
Problem: flux-batch.rst includes content from common/submit-submission-directives.rst because it was shared with flux-mini.rst but flux-mini(1) is no more. Move that content into flux-batch.rst.
Problem: flux-watch(1) lists its title as "flux-jobs". Fix title.
Problem: the EXIT STATUS section of the job submission commands reference flux-run(1) but have a typo in the role causing it to render improperly. Fix typo.
Problem: command line options do not stand out in the HTML rendering and do not have HTML tags for cross referencing. Use the 'option' directive[1], which causes options to stand out and also opens the door to cross referencing of options. Note we have some man pages like flux-kvs(1) that describe options in a compressed paragraph form rather than breaking them out in a list. Those pages were left alone by this commit. [1]https://www.sphinx-doc.org/en/master/usage/domains/standard.html
Codecov Report
@@ Coverage Diff @@
## master #5521 +/- ##
==========================================
- Coverage 83.46% 83.45% -0.01%
==========================================
Files 487 487
Lines 82011 82011
==========================================
- Hits 68450 68446 -4
- Misses 13561 13565 +4 |
grondo
approved these changes
Nov 1, 2023
| @@ -5,7 +5,6 @@ | |||
| flux-alloc(1) | |||
| ============= | |||
|
|
|||
|
|
|||
There was a problem hiding this comment.
commit message:
"cross-reference tags for options are relative" ➡️ "...options that are relative"?
There was a problem hiding this comment.
Oh, actually it's the tags that are relative not the options. I'll reword, it's an awkward sentence.
Problem: the HTML cross-reference tags that are automatically generated for declared options point to a path that is relative to the document basename name rather than the command or sub-command name, which could be ambiguous. For example, consider the flux job attach "-l, --label-io" option. The auto-generated tag is "flux-job.html#cmdoption-l" As noted in [1], the 'program' directive notifies Sphinx that all following option directives document options for the named program. After declaring the program to be "flux job attach", the tag becomes: "flux-job.html#cmdoption-flux-job-attach-l". References to the option with the program name in it like :option:`flux job attach -l` or :option:`flux job attach --label-io` become hyperlinks to the option description within the page containing the program. Note that a program directive remains in effect when included text is processed. This means that options declared in common/*.rst are properly tagged when included from other pages. For example, the "-N, --nodes=N" option in flux-batch(1) is "flux-batch.html#cmdoption-flux-batch-N", while in flux-run(1) it is "flux-run.html#cmdoption-flux-run-N". [1]https://www.sphinx-doc.org/en/master/usage/domains/standard.html
Problem: when referring to options, we usually just quote them as a literal string, which is ugly in the HTML rendering and does not allow sphinx to cross-reference references to descriptions. Use the :option: directive to tie option references to their description in the HTML. This also improves the HTML rendering. The cross references are particularly helpful in the job submission command options, where there are many options and some need to refer to others. It should be OK to use the :option: directive with any option string since, at a minimum, it helps unify their presentation. However Sphinx only cross-references certain option string formats. Consider this example: .. program:: flux run .. option:: -o, --option=OPTS The following are cross-referenced: :option:`-o` :option:`--option` :option:`flux run --option` The following are not cross-referenced by sphinx 3.4.3, but the documentation implies the first two should work in sphinx 5.3: :option:`--option=OPTS` :option:`--option=pty.interactive` :option:`-o, --option` In this commit, all of the above are deemed acceptable markup, athough in some cases the last format was converted to the long option alone when it wasn't the only documentation of the short option. This commit only addresses option formatting, although some lines were re-broken in the .rst files to avoid going over 79 columns. Note: this commit is not a complete conversion of all option strings across section 1. It only touches some of the more widely used and/or easy to convert pages.
Problem: program names are not consistently formatted. Use :program: to format program names. This is purely a formatting role and does not generate any cross-reference data. Use :option: to format a program name with options, to cross-reference to the option description. https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Problem: man pages contain several "See section ..." references but the HTML does not link there. Improve section cross-referencing. Sections within a document can be referenced with `SECTION NAME`_ and outside of a document can be referenced via :ref: as described here https://www.sphinx-doc.org/en/master/usage/referencing.html
|
Thank you! I fixed that commit message and I'll set MWP. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
This adds sphinx markup to our section 1 manual pages to improve HTML rendering and cross referencing. Most of this was already presented in #5520.
This should be purely formatting changes, although some line breaks in the
.rstfiles needed to be adjusted to avoid making lines too long.