Merge pull request #4426 from garlick/queue_1

flux-queue(1): add man page

doc/Makefile.am

@@ -28,6 +28,7 @@ MAN1_FILES_PRIMARY = \
 	man1/flux-content.1 \
 	man1/flux-config.1 \
 	man1/flux-proxy.1 \
+	man1/flux-queue.1 \
 	man1/flux-cron.1 \
 	man1/flux-event.1 \
 	man1/flux-mini.1 \

doc/man1/flux-queue.rst

@@ -0,0 +1,86 @@
+.. flux-help-description: Manipulate flux queues
+
+=============
+flux-queue(1)
+=============
+
+
+SYNOPSIS
+========
+
+**flux** **queue** **disable** *reason...*
+
+**flux** **queue** **enable**
+
+**flux** **queue** **stop** [*--verbose*] [*--quiet*]
+
+**flux** **queue** **start** [*--verbose*] [*--quiet*]
+
+**flux** **queue** **status** [*--verbose*]
+
+**flux** **queue** **drain** [*--timeout=DURATION*]
+
+**flux** **queue** **idle** [*--quiet*] [*--timeout=DURATION*]
+
+DESCRIPTION
+===========
+
+The ``flux-queue`` command controls the Flux job queue.
+It has the following subcommands:
+
+disable
+  Prevent jobs from being submitted to the queue, with `reason` that is
+  shown to submitting users.
+
+enable
+  Allow jobs to be submitted to the queue.
+
+stop
+  Stop allocating resources to jobs.  Pending jobs remain in the queue,
+  and running jobs continue to run, but no new jobs are allocated resources.
+
+start
+  Start allocating resources to jobs.
+
+status
+  Report the current queue status.
+
+drain
+  Block until the queue becomes empty.  It is sometimes useful to run after
+  ``flux queue disable``, to wait until the system is quiescent and can be
+  taken down for maintenance.
+
+idle
+  Block until the queue becomes `idle` (no jobs in RUN or CLEANUP state,
+  and no outstanding alloc requests to the scheduler).  It may be useful to run
+  after ``flux queue stop`` to wait until the scheduler and execution system
+  are quiescent before maintenance involving them.
+
+OPTIONS
+=======
+
+**-h, --help**
+   Summarize available options.
+
+**-v, --verbose**
+   Be chatty.
+
+**-q, --quiet**
+   Be taciturn.
+
+**--timeout** \ =\ *FSD*
+   Limit the time that ``drain`` or ``idle`` will block.
+
+
+RESOURCES
+=========
+
+Flux: http://flux-framework.org
+
+RFC 23: Flux Standard Duration: https://flux-framework.readthedocs.io/projects/flux-rfc/en/latest/spec_23.html
+
+
+SEE ALSO
+========
+
+:man1:`flux-jobs`, :man1:`flux-mini`

doc/man1/index.rst

@@ -26,6 +26,7 @@ man1
    flux-ping
    flux-proxy
    flux-pstree
+   flux-queue
    flux-resource
    flux-restore
    flux-start

doc/manpages.py

@@ -45,6 +45,7 @@
     ('man1/flux-module', 'flux-module', 'manage Flux extension modules', [author], 1),
     ('man1/flux-ping', 'flux-ping', 'measure round-trip latency to Flux services', [author], 1),
     ('man1/flux-proxy', 'flux-proxy', 'create proxy environment for Flux instance', [author], 1),
+    ('man1/flux-queue', 'flux-queue', 'manage the job queue', [author], 1),
     ('man1/flux-start', 'flux-start', 'bootstrap a local Flux instance', [author], 1),
     ('man1/flux-startlog', 'flux-startlog', 'Show Flux instance start and stop times', [author], 1),
     ('man1/flux-top', 'flux-top', 'Display running Flux jobs', [author], 1),