From fd9c8d2d2662d21fb0d82924f8ea487565039b89 Mon Sep 17 00:00:00 2001 From: Jim Garlick Date: Sun, 29 Oct 2023 14:33:25 -0700 Subject: [PATCH] man1: improve section cross-referencing 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 --- doc/man1/common/submit-environment.rst | 2 +- doc/man1/common/submit-other-options.rst | 2 +- doc/man1/flux-config.rst | 2 +- doc/man1/flux-exec.rst | 2 +- doc/man1/flux-jobs.rst | 13 +++++++++---- doc/man1/flux-pstree.rst | 4 ++-- doc/man1/flux-queue.rst | 2 +- doc/man1/flux-resource.rst | 12 +++++++----- doc/man1/flux-shell.rst | 10 +++++----- doc/man1/flux-start.rst | 2 +- doc/man1/flux-top.rst | 2 +- doc/man1/flux-update.rst | 2 +- 12 files changed, 31 insertions(+), 24 deletions(-) diff --git a/doc/man1/common/submit-environment.rst b/doc/man1/common/submit-environment.rst index 1fff0d6f3a0b..9f53b668fb5b 100644 --- a/doc/man1/common/submit-environment.rst +++ b/doc/man1/common/submit-environment.rst @@ -8,7 +8,7 @@ give fine control over the requested environment submitted with the job. .. option:: --env=RULE Control how environment variables are exported with *RULE*. See - *ENV RULE SYNTAX* section below for more information. Rules are + the `ENV RULES`_ section below for more information. Rules are applied in the order in which they are used on the command line. This option may be specified multiple times. diff --git a/doc/man1/common/submit-other-options.rst b/doc/man1/common/submit-other-options.rst index 9a43222625a4..6d1c1d0023c0 100644 --- a/doc/man1/common/submit-other-options.rst +++ b/doc/man1/common/submit-other-options.rst @@ -27,7 +27,7 @@ OTHER OPTIONS Set shell option. Keys may include periods to denote hierarchy. VAL is optional and may be valid JSON (bare values, objects, or arrays), otherwise VAL is interpreted as a string. If VAL is not set, then the - default value is 1. See SHELL OPTIONS below. + default value is 1. See `SHELL OPTIONS`_ below. .. option:: --setattr=KEY[=VAL] diff --git a/doc/man1/flux-config.rst b/doc/man1/flux-config.rst index 56313a121e94..b8e7269ec72d 100644 --- a/doc/man1/flux-config.rst +++ b/doc/man1/flux-config.rst @@ -37,7 +37,7 @@ string values, which are printed without quotes to simplify their use in shell scripts. :program:`flux config builtin` prints compiled-in Flux configuration values. -See BUILTIN VALUES below for a list of builtin +See `BUILTIN VALUES`_ below for a list of builtin configuration key names. This command is available to all users. .. note:: diff --git a/doc/man1/flux-exec.rst b/doc/man1/flux-exec.rst index fa7fe31bd606..4efca62b573e 100644 --- a/doc/man1/flux-exec.rst +++ b/doc/man1/flux-exec.rst @@ -61,7 +61,7 @@ OPTIONS .. option:: -r, --rank=NODESET Target specific ranks in *NODESET*. Default is to target "all" ranks. - See NODESET FORMAT below for more information. + See `NODESET FORMAT`_ below for more information. .. option:: -v, --verbose diff --git a/doc/man1/flux-jobs.rst b/doc/man1/flux-jobs.rst index 9c34c5c92591..f7f3b8e266b0 100644 --- a/doc/man1/flux-jobs.rst +++ b/doc/man1/flux-jobs.rst @@ -70,18 +70,18 @@ OPTIONS .. option:: -f, --filter=STATE|RESULT List jobs with specific job state or result. Multiple states or - results can be listed separated by comma. See JOB STATUS below for + results can be listed separated by comma. See `JOB STATUS`_ below for additional information. Defaults to *pending,running*. .. option:: -o, --format=NAME|FORMAT Specify a named output format *NAME* or a format string using Python's - format syntax. See OUTPUT FORMAT below for field names. Named formats + format syntax. See `OUTPUT FORMAT`_ below for field names. Named formats may be listed via :option:`--format=help`. An alternate default format can be set via the FLUX_JOBS_FORMAT_DEFAULT environment variable. Additional named formats may be registered with :program:`flux jobs` via configuration. - See the CONFIGURATION section for more details. A configuration snippet for - an existing named format may be generated with + See the `CONFIGURATION`_ section for more details. A configuration snippet + for an existing named format may be generated with :option:`--format=get-config=NAME`. .. option:: --json @@ -173,6 +173,7 @@ OPTIONS threads is used, but by using the :option:`--threads`, a specific number of threads can be chosen. +.. _flux_jobs_job_status: JOB STATUS ========== @@ -195,6 +196,8 @@ FAILED, CANCELED, or TIMEOUT. Under the *status_abbrev* field name, these are abbreviated as D, S, R, C, CD, F, CA, and TO respectively. +.. _flux_jobs_output_format: + OUTPUT FORMAT ============= @@ -491,6 +494,8 @@ the state of the job or other context: will also be provided such as the exit ``returncode`` or cancellation message. +.. _flux_jobs_configuration: + CONFIGURATION ============= diff --git a/doc/man1/flux-pstree.rst b/doc/man1/flux-pstree.rst index e0dbfbe9b89c..69041612c64e 100644 --- a/doc/man1/flux-pstree.rst +++ b/doc/man1/flux-pstree.rst @@ -99,8 +99,8 @@ OPTIONS .. option:: -f, --filter=STATE|RESULT Include jobs with specific job state or result. Multiple states or - results can be listed separated by comma. See the JOB STATUS section - of the :man1:`flux-jobs` manual for more detail. + results can be listed separated by comma. See the :ref:`flux_jobs_job_status` + section of the :man1:`flux-jobs` manual for more detail. .. option:: -l, --long diff --git a/doc/man1/flux-queue.rst b/doc/man1/flux-queue.rst index b7ca234c68e2..707c546b4f85 100644 --- a/doc/man1/flux-queue.rst +++ b/doc/man1/flux-queue.rst @@ -121,7 +121,7 @@ OPTIONS .. option:: -o, --format=FORMAT Specify output format in ``list`` using Python's string format syntax. - See OUTPUT FORMAT below for field names. + See `OUTPUT FORMAT`_ below for field names. OUTPUT FORMAT diff --git a/doc/man1/flux-resource.rst b/doc/man1/flux-resource.rst index c8562deb0043..b3b4fd113c3e 100644 --- a/doc/man1/flux-resource.rst +++ b/doc/man1/flux-resource.rst @@ -63,7 +63,7 @@ COMMANDS to include only those ranks or hosts that are present in *TARGETS*. The :option:`-o,--format=FORMAT` option may be used to customize the output - format (See OUTPUT FORMAT section below). + format (See `OUTPUT FORMAT`_ section below). The :option:`-n,--no-header` option suppresses header from output, @@ -120,7 +120,7 @@ COMMANDS filtered to include only those ranks or hosts that are present in *TARGETS*. The :option:`-o,--format=FORMAT` option customizes output formatting (See - the OUTPUT FORMAT section below for details). + the `OUTPUT FORMAT`_ section below for details). With :option:`-n,--no-header` the output header is suppressed. @@ -175,13 +175,15 @@ OUTPUT FORMAT The :option:`--format` option can be used to specify an output format using Python's string format syntax or a defined format by name. For a list of built-in and configured formats use :option:`-o help`. An alternate default +<<<<<<< HEAD format can be set via the FLUX_RESOURCE_STATUS_FORMAT_DEFAULT, FLUX_RESOURCE_DRAIN_FORMAT_DEFAULT, and FLUX_RESOURCE_LIST_FORMAT_DEFAULT environment variables (for :program:`flux resource status`, :program:`flux resource drain`, and :program:`flux resource list` respectively). A configuration snippet for an existing named format may be generated with :option:`--format=get-config=NAME`. See :man1:`flux-jobs` -*OUTPUT FORMAT* section for a detailed description of this syntax. +:ref:`flux_jobs_output_format` section for a detailed description of this +syntax. Resources are combined into a single line of output when possible depending on the supplied output format. Resource counts are not included in the @@ -280,8 +282,8 @@ the following config file could be used:: description = "My flux resource list format" format = "{state} {nodelist}" -See :man1:`flux-jobs` *CONFIGURATION* section for more information about the -order of precedence for loading these config files. +See :man1:`flux-jobs` :ref:`flux_jobs_configuration` section for more +information about the order of precedence for loading these config files. RESOURCE INVENTORY ================== diff --git a/doc/man1/flux-shell.rst b/doc/man1/flux-shell.rst index ed3ae6f0764b..4ed0b0678086 100644 --- a/doc/man1/flux-shell.rst +++ b/doc/man1/flux-shell.rst @@ -25,13 +25,13 @@ The design of the Flux job shell allows customization through a set of builtin and runtime loadable shell plugins. These plugins are used to handle standard I/O redirection, PMI, CPU and GPU affinity, debugger support and more. Details of the :program:`flux shell` plugin capabilities and -design can be found in the PLUGINS section below. +design can be found in the `PLUGINS`_ section below. :program:`flux shell` also supports configuration via a Lua-based configuration file, called the shell ``initrc``, from which shell plugins may be loaded or shell options and data examined or set. The :program:`flux shell` initrc may even extend the shell itself via simple shell plugins developed directly -in Lua. See the SHELL INITRC section below for details of the ``initrc`` +in Lua. See the `SHELL INITRC`_ section below for details of the ``initrc`` format and features. OPTIONS @@ -66,7 +66,7 @@ execution of the job: typically ``-shell-`` * load the system default ``initrc.lua`` (``$sysconfdir/flux/shell/initrc.lua``), unless overridden by - configuration (See JOBSPEC OPTIONS and INITRC sections below) + configuration (See `JOBSPEC OPTIONS`_ and `SHELL INITRC`_ sections below) * call ``shell.init`` plugin callbacks * change working directory to the cwd of the job * enter a barrier to ensure shell initialization is complete on all shells @@ -117,7 +117,7 @@ These callbacks are defined by "topic strings" to which plugins can the shell option is set before the builtin attempts to read them. Simple plugins may also be developed directly in the shell ``initrc.lua`` -file itself (see INITRC section, ``plugin.register()`` below) +file itself (see `SHELL INITRC`_ section, ``plugin.register()`` below) By default, :program:`flux shell` supports the following plugin callback topics: @@ -207,7 +207,7 @@ Options supported by :program:`flux shell` proper include: **initrc**\ =\ *FILE* Load :program:`flux shell` initrc.lua file from *FILE* instead of the default initrc path. For details of the job shell initrc.lua file format, - see the INITRC section below. + see the `SHELL INITRC`_ section below. Job shell plugins may also support configuration via shell options in the jobspec. For specific information about runtime-loaded plugins, diff --git a/doc/man1/flux-start.rst b/doc/man1/flux-start.rst index 79e8f73367e0..fff858a00c0f 100644 --- a/doc/man1/flux-start.rst +++ b/doc/man1/flux-start.rst @@ -36,7 +36,7 @@ OPTIONS .. option:: -v, --verbose=[LEVEL] This option may be specified multiple times, or with a value, to - set a verbosity level. See VERBOSITY LEVELS below. + set a verbosity level. See `VERBOSITY LEVELS`_ below. .. option:: -X, --noexec diff --git a/doc/man1/flux-top.rst b/doc/man1/flux-top.rst index ea25ced5e95d..61352567cc5b 100644 --- a/doc/man1/flux-top.rst +++ b/doc/man1/flux-top.rst @@ -86,7 +86,7 @@ The summary pane shows the following information: - The amount of time until the job's expiration time, in Flux Standard Duration format. If the expiration time is unknown, the infinity symbol is - displayed (see CAVEATS below). + displayed (see `CAVEATS`_ below). - The nodes bargraph, which shows the fraction of used and down/excluded nodes vs total nodes. The graph of used nodes is colored yellow and extends from diff --git a/doc/man1/flux-update.rst b/doc/man1/flux-update.rst index b94112e76f04..81a2efbdded0 100644 --- a/doc/man1/flux-update.rst +++ b/doc/man1/flux-update.rst @@ -29,7 +29,7 @@ would request an update of ``attributes.system.myattr`` to the string value ``"value"``. The :program:`flux update` command may also support other convenient key -aliases. Key aliases are listed in the SPECIAL KEYS section below. +aliases. Key aliases are listed in the `SPECIAL KEYS`_ section below. Updates will be sent to the job manager update service, which checks that the current user is permitted to apply all updates, and that all updates