From b41b2f1432baa1dc6025aa7f66bb9e6c94073587 Mon Sep 17 00:00:00 2001
From: Jim Garlick <garlick.jim@gmail.com>
Date: Tue, 24 May 2022 13:56:12 -0700
Subject: [PATCH] flux-queue(1): add man page

Problem: flux-queue has no man page, but some of the terms it uses
are non-obvious.

Add a new man page.
---
 doc/Makefile.am         |  1 +
 doc/man1/flux-queue.rst | 86 +++++++++++++++++++++++++++++++++++++++++
 doc/man1/index.rst      |  1 +
 doc/manpages.py         |  1 +
 4 files changed, 89 insertions(+)
 create mode 100644 doc/man1/flux-queue.rst

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 5554a1df025b..720d3ccaef56 100644
--- a/doc/Makefile.am
+++ b/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 \
diff --git a/doc/man1/flux-queue.rst b/doc/man1/flux-queue.rst
new file mode 100644
index 000000000000..b0f061b235ba
--- /dev/null
+++ b/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`
diff --git a/doc/man1/index.rst b/doc/man1/index.rst
index 6bd926ae1561..3132cffca2ab 100644
--- a/doc/man1/index.rst
+++ b/doc/man1/index.rst
@@ -26,6 +26,7 @@ man1
    flux-ping
    flux-proxy
    flux-pstree
+   flux-queue
    flux-resource
    flux-restore
    flux-start
diff --git a/doc/manpages.py b/doc/manpages.py
index f29ebd817744..b75534c508b8 100644
--- a/doc/manpages.py
+++ b/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),