Merge pull request #5521 from garlick/man1_pretty

man1: improve HTML formatting of man pages

doc/Makefile.am

@@ -33,7 +33,6 @@ MAN1_FILES_PRIMARY = \
 	man1/flux-queue.1 \
 	man1/flux-cron.1 \
 	man1/flux-event.1 \
-	man1/flux-mini.1 \
 	man1/flux-submit.1 \
 	man1/flux-run.1 \
 	man1/flux-bulksubmit.1 \
@@ -342,9 +341,7 @@ $(RST_FILES): \
 	man1/common/submit-process-resource-limits.rst \
 	man1/common/submit-exit-status.rst \
 	man1/common/submit-other-options.rst \
-	man1/common/submit-bulksubmit.rst \
 	man1/common/submit-shell-options.rst \
-	man1/common/submit-submission-directives.rst \
 	man3/common/json_pack.rst \
 	man3/common/json_unpack.rst
 endif
@@ -403,9 +400,6 @@ EXTRA_DIST = \
 	guide/glossary.rst \
 	$(RST_FILES) \
 	man1/index.rst \
-	man1/index_general.rst \
-	man1/index_job.rst \
-	man1/index_kvs.rst \
 	man1/common/nodeset.rst \
 	man1/common/submit-job-parameters.rst \
 	man1/common/submit-standard-io.rst \
@@ -416,9 +410,7 @@ EXTRA_DIST = \
 	man1/common/submit-process-resource-limits.rst \
 	man1/common/submit-exit-status.rst \
 	man1/common/submit-other-options.rst \
-	man1/common/submit-bulksubmit.rst \
 	man1/common/submit-shell-options.rst \
-	man1/common/submit-submission-directives.rst \
 	man3/index.rst \
 	man3/index_general.rst \
 	man3/index_idset.rst \

doc/man1/common/submit-constraints.rst

@@ -1,7 +1,8 @@
 CONSTRAINTS
 ===========
 
-**--requires=CONSTRAINT**
+.. option:: --requires=CONSTRAINT**
+
    Specify a set of allowable properties and other attributes to consider
    when matching resources for a job. The **CONSTRAINT** is expressed in
    a simple syntax described in RFC 35 (Constraint Query Syntax) which is
@@ -29,7 +30,7 @@ CONSTRAINTS
 
    The full specification of Constraint Query Syntax can be found in RFC 35.
 
-   Currently, **--requires** supports the following operators:
+   Currently, :option:`--requires` supports the following operators:
 
    properties
      Require the set of specified properties. Properties may be

doc/man1/common/submit-dependencies.rst

@@ -8,7 +8,8 @@ DEPENDENCIES
 
 Dependencies may be specified on the command line using the following options:
 
-**--dependency=URI**
+.. option:: --dependency=URI
+
    Specify a dependency of the submitted job using RFC 26 dependency URI
    format. The URI format is **SCHEME:VALUE[?key=val[&key=val...]]**.
    The URI will be converted into RFC 26 JSON object form and appended to
@@ -17,7 +18,7 @@ Dependencies may be specified on the command line using the following options:
    submitted job will be rejected with an error message indicating this
    fact.
 
-   The ``--dependency`` option may be specified multiple times. Each use
+   The :option:`--dependency` option may be specified multiple times. Each use
    appends a new dependency object to the ``attributes.system.dependencies``
    array.
 

doc/man1/common/submit-environment.rst

@@ -5,27 +5,30 @@ By default, these commands duplicate the current environment when submitting
 jobs. However, a set of environment manipulation options are provided to
 give fine control over the requested environment submitted with the job.
 
-**--env=RULE**
+.. 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.
 
-**--env-remove=PATTERN**
+.. option:: --env-remove=PATTERN
+
    Remove all environment variables matching *PATTERN* from the current
    generated environment. If *PATTERN* starts with a ``/`` character,
    then it is considered a :linux:man7:`regex`, otherwise *PATTERN* is
    treated as a shell :linux:man7:`glob`. This option is equivalent to
-   ``--env=-PATTERN`` and may be used multiple times.
+   :option:`--env=-PATTERN` and may be used multiple times.
+
+.. option:: --env-file=FILE
 
-**--env-file=FILE**
    Read a set of environment *RULES* from a *FILE*. This option is
-   equivalent to ``--env=^FILE`` and may be used multiple times.
+   equivalent to :option:`--env=^FILE` and may be used multiple times.
 
 ENV RULES
 =========
 
-The ``--env*`` options allow control of the environment exported to jobs
+The `ENVIRONMENT`_ options allow control of the environment exported to jobs
 via a set of *RULE* expressions. The currently supported rules are
 
  * If a rule begins with ``-``, then the rest of the rule is a pattern
@@ -74,8 +77,8 @@ via a set of *RULE* expressions. The currently supported rules are
        ``PATH``, ``FLUX_*_PATH``, ``/^OMP.*/``
 
 Since we always starts with a copy of the current environment,
-the default implicit rule is ``*`` (or ``--env=*``). To start with an
-empty environment instead, the ``-*`` rule or ``--env-remove=*`` option
+the default implicit rule is ``*`` (or :option:`--env=*`). To start with an
+empty environment instead, the ``-*`` rule or :option:`--env-remove=*` option
 should be used. For example, the following will only export the current
 ``PATH`` to a job:
 
@@ -85,8 +88,9 @@ should be used. For example, the following will only export the current
 
 
 Since variables can be expanded from the currently built environment, and
-``--env`` options are applied in the order they are used, variables can
-be composed on the command line by multiple invocations of ``--env``, e.g.:
+:option:`--env` options are applied in the order they are used, variables can
+be composed on the command line by multiple invocations of :option:`--env`,
+e.g.:
 
 ::
 

doc/man1/common/submit-exit-status.rst

@@ -7,6 +7,6 @@ the job exit status is 128+signo.
 
 The ``flux-job attach`` command exits with the job exit status.
 
-In addition, :man:`flux-run` runs until the job completes and exits
+In addition, :man1:`flux-run` runs until the job completes and exits
 with the job exit status.
 

doc/man1/common/submit-job-parameters.rst

@@ -9,19 +9,22 @@ Common resource options
 
 These commands take the following common resource allocation options:
 
-**-N, --nodes=N**
+.. option:: -N, --nodes=N
+
    Set the number of nodes to assign to the job. Tasks will be distributed
    evenly across the allocated nodes, unless the per-resource options
    (noted below) are used with *submit*, *run*, or *bulksubmit*. It is
    an error to request more nodes than there are tasks. If unspecified,
    the number of nodes will be chosen by the scheduler.
 
-**-x, --exclusive**
+.. option:: -x, --exclusive
+
    Indicate to the scheduler that nodes should be exclusively allocated to
    this job. It is an error to specify this option without also using
-   *-N, --nodes*. If *--nodes* is specified without *--nslots* or *--ntasks*,
-   then this option will be enabled by default and the number of tasks
-   or slots will be set to the number of requested nodes.
+   :option:`--nodes`. If :option:`--nodes` is specified without
+   :option:`--nslots` or :option:`--ntasks`, then this option will be enabled
+   by default and the number of tasks or slots will be set to the number of
+   requested nodes.
 
 
 Per-task options
@@ -33,13 +36,16 @@ The most common form uses the total number of tasks to run along with
 the amount of resources required per task to specify the resources for
 the entire job:
 
-**-n, --ntasks=N**
+.. option:: -n, --ntasks=N
+
    Set the number of tasks to launch (default 1).
 
-**-c, --cores-per-task=N**
+.. option:: -c, --cores-per-task=N
+
    Set the number of cores to assign to each task (default 1).
 
-**-g, --gpus-per-task=N**
+.. option:: -g, --gpus-per-task=N
+
    Set the number of GPU devices to assign to each task (default none).
 
 Per-resource options
@@ -50,19 +56,23 @@ with the number of tasks per core or node set on the command line. It is
 an error to specify any of these options when using any per-task option
 listed above:
 
-**--cores=N**
+.. option:: --cores=N
+
    Set the total number of cores.
 
-**--tasks-per-node=N**
+.. option:: --tasks-per-node=N
+
    Set the number of tasks per node to run.
 
-**--gpus-per-node=N**
-   With -N, --nodes, request a specific number of GPUs per node.
+.. option:: --gpus-per-node=N
+
+   With :option:`--nodes`, request a specific number of GPUs per node.
+
+.. option:: --tasks-per-core=N
 
-**--tasks-per-core=N**
    Force a number of tasks per core. Note that this will run *N* tasks per
    *allocated* core. If nodes are exclusively scheduled by configuration or
-   use of the ``--exclusive`` flag, then this option could result in many
+   use of the :option:`--exclusive` flag, then this option could result in many
    more tasks than expected. The default for this option is effectively 1,
    so it is useful only for oversubscribing tasks to cores for testing
    purposes. You probably don't want to use this option.
@@ -75,39 +85,47 @@ therefore job parameters are specified in terms of resource slot size
 and number of slots. A resource slot can be thought of as the minimal
 resources required for a virtual task. The default slot size is 1 core.
 
-**-n, --nslots=N**
+.. option:: -n, --nslots=N
+
    Set the number of slots requested. This parameter is required.
 
-**-c, --cores-per-slot=N**
+.. option:: -c, --cores-per-slot=N
+
    Set the number of cores to assign to each slot (default 1).
 
-**-g, --gpus-per-slot=N**
+.. option:: -g, --gpus-per-slot=N
+
    Set the number of GPU devices to assign to each slot (default none).
 
 Additional job options
 ----------------------
 
 These commands also take following job parameters:
 
-**-q, --queue=NAME**
+.. option:: -q, --queue=NAME
+
    Submit a job to a specific named queue. If a queue is not specified
    and queues are configured, then the jobspec will be modified at ingest
    to specify the default queue. If queues are not configured, then this
    option is ignored, though :man1:`flux-jobs` may display the queue
    name in its rendering of the ``{queue}`` attribute.
 
-**-t, --time-limit=MINUTES|FSD**
+.. option:: -t, --time-limit=MINUTES|FSD
+
    Set a time limit for the job in either minutes or Flux standard duration
    (RFC 23). FSD is a floating point number with a single character units
-   suffix ("s", "m", "h", or "d"). The default unit for the ``--time-limit``
-   option is minutes when no units are otherwise specified. If the time
-   limit is unspecified, the job is subject to the system default time limit.
+   suffix ("s", "m", "h", or "d"). The default unit for the
+   :option:`--time-limit` option is minutes when no units are otherwise
+   specified. If the time limit is unspecified, the job is subject to the
+   system default time limit.
+
+.. option:: --job-name=NAME
 
-**--job-name=NAME**
    Set an alternate job name for the job.  If not specified, the job name
    will default to the command or script executed for the job.
 
-**--flags=FLAGS**
+.. option:: --flags=FLAGS
+
    Set comma separated list of job submission flags.  The possible flags are
    ``waitable``, ``novalidate``, and ``debug``.  The ``waitable`` flag will
    allow the job to be waited on via ``flux job wait`` and similar API calls.