doc: add man(1) pages for user commands

Problem: flux-accounting has no man(1) pages for any of the subcommands
that deal with user administration.

Add man(1) entries for view-user, add-user, delete-user, and edit-user.

doc/Makefile.am

@@ -11,7 +11,11 @@ MAN1_FILES_PRIMARY = \
 	man1/flux-account.1 \
 	man1/flux-account-create-db.1 \
 	man1/flux-account-pop-db.1 \
-	man1/flux-account-export-db.1
+	man1/flux-account-export-db.1 \
+	man1/flux-account-view-user.1 \
+	man1/flux-account-add-user.1 \
+	man1/flux-account-delete-user.1 \
+	man1/flux-account-edit-user.1
 
 MAN5_FILES_PRIMARY = \
 	man5/flux-config-accounting.5

doc/man1/flux-account-add-user.rst

@@ -0,0 +1,82 @@
+.. flux-help-section: flux account
+
+========================
+flux-account-add-user(1)
+========================
+
+
+SYNOPSIS
+========
+
+**flux** **account** **add-user** --username=USERNAME --bank=BANK [OPTIONS]
+
+DESCRIPTION
+===========
+
+.. program:: flux account add-user
+
+:program:`flux account add-user` will add an *association* to the
+``association_table`` in the flux-accounting database. An *association* is
+defined as a 2-tuple combination of a username and bank name. It requires two
+arguments: the *username* of the association and the *bank* they are being
+added under. Additional configurable fields, such as the number of allocated
+shares, a default bank, various job limits, permissible queues, etc. may also
+be defined upon user creation.
+
+.. option:: --username
+
+    The username of the association.
+
+.. option:: --userid
+
+    The userid of the association.
+
+.. option:: --bank
+
+    The bank of the association. Users submitting jobs under this bank will
+    contribute both to their own usage as well as the bank's total usage.
+
+.. option:: --shares
+
+    The amount of available resources their organization considers they should
+    be entitled to use relative to other competing users.
+
+.. option:: --max-running-jobs
+
+    The max number of running jobs the association can have at any given time.
+
+.. option:: --max-active-jobs
+
+    The max number of both pending and running jobs the association can have at
+    any given time.
+
+.. option:: --max-nodes
+
+    The max number of nodes an association can have across all of their running
+    jobs.
+
+.. option:: --queues
+
+    A comma-separated list of all of the queues an association can run jobs
+    under.
+
+.. option:: --projects
+
+    A comma-separated list of all of the projects an association can run jobs
+    under.
+
+EXAMPLES
+--------
+
+An association can be added to the flux-accounting database simply by
+specifying the username and the bank name:
+
+.. code-block:: console
+
+ $ flux account add-user --username=moose --bank=bankA
+
+Or fully configured by specifying any additional number of options:
+
+.. code-block:: console
+
+ $ flux account add-user --username=moose --bank=bankA --queues=queue1,queue2 --shares=1

doc/man1/flux-account-delete-user.rst

@@ -0,0 +1,37 @@
+.. flux-help-section: flux account
+
+===========================
+flux-account-delete-user(1)
+===========================
+
+
+SYNOPSIS
+========
+
+**flux** **account** **delete-user** USERNAME BANK
+
+DESCRIPTION
+===========
+
+.. program:: flux account delete-user
+
+:program:`flux account delete-user` will set an association's ``active``
+field to ``0`` in the ``association_table``, disabling them from being able
+to submit and run jobs. It will not remove the association from the SQLite
+database, however, as their job usage can still contribute to their bank's
+fair-share up until the job usage reset period. Associations can be reactivated
+by simply re-adding them to the ``association_table`` with
+``flux account add-user``.
+
+To actually remove an association from the ``association_table``, pass the
+``--force`` option.
+
+.. warning::
+    Permanently deleting rows from the ``association_table`` or ``bank_table``
+    can affect the fair-share calculation for other rows in their respective
+    tables. Proceed with caution when deleting rows with ``--force``.
+
+SEE ALSO
+========
+
+:man1:`flux-account-add-user`

doc/man1/flux-account-edit-user.rst

@@ -0,0 +1,88 @@
+.. flux-help-section: flux account
+
+=========================
+flux-account-edit-user(1)
+=========================
+
+
+SYNOPSIS
+========
+
+**flux** **account** **edit-user** USERNAME [--bank=BANK] [OPTIONS]
+
+DESCRIPTION
+===========
+
+.. program:: flux account edit-user
+
+:program:`flux account edit-user` allows for the modifications of certain
+fields for a given association. The list of modifiable fields are as follows:
+
+.. option:: --userid
+
+    The userid of the association.
+
+.. option:: --bank
+
+    An optional bank name that can be specified. If left out, the update will
+    be applied across all of the rows in ``association_table`` where
+    ``username`` is found.
+
+.. option:: --shares
+
+    The amount of available resources their organization considers they should
+    be entitled to use relative to other competing users.
+
+.. option:: --fairshare
+
+    The ratio between the amount of resources an association is allocated
+    versus the amount actually consumed.
+
+.. option:: --max-running-jobs
+
+    The max number of running jobs the association can have at any given time.
+
+.. option:: --max-active-jobs
+
+    The max number of both pending and running jobs the association can have at
+    any given time.
+
+.. option:: --max-nodes
+
+    The man number of nodes an association can have across all of their running
+    jobs.
+
+.. option:: --queues
+
+    A comma-separated list of all of the queues an association can run jobs
+    under.
+
+.. option:: --projects
+
+    A comma-separated list of all of the projects an association can run jobs
+    under.
+
+.. option:: --default-project
+
+    The default project the association will submit jobs under when they do not
+    specify a project.
+
+All of the attributes able to be modified can be reset to their default value
+by passing ``-1`` as the value for the field. Multiple fields can be edited at
+the same time by passing them on the command line.
+
+EXAMPLES
+--------
+
+Multiple attributes for an association can be edited at the same time:
+
+.. code-block:: console
+
+    $ flux account edit-user moose --max-active-jobs=100 --queues="special,expedite"
+
+An association's attributes can be reset to their default value by passing
+``-1``:
+
+.. code-block:: console
+
+    $ flux account edit-user moose --max-active-jobs=-1

doc/man1/flux-account-view-user.rst

@@ -0,0 +1,33 @@
+.. flux-help-section: flux account
+
+=========================
+flux-account-view-user(1)
+=========================
+
+
+SYNOPSIS
+========
+
+**flux** **account** **view-user** USERNAME [OPTIONS]
+
+DESCRIPTION
+===========
+
+.. program:: flux account view-user
+
+:program:`flux account view-user` returns all of the various attributes for
+every bank that a user belongs to (i.e every **association** that contains
+USERNAME). Information about the user can be formatted in a parsable format as
+well as customizing which fields are returned.
+
+.. option:: --parsable
+
+    Prints all information about each association on one line.
+
+.. option:: --fields
+
+    Customize which fields are returned in the output of ``view-user``.
+
+.. option:: --list-banks
+
+    Concisely list all of the banks a user belongs to.

doc/man1/flux-account.rst

@@ -51,15 +51,31 @@ USER ADMINISTRATION
 view-user
 ^^^^^^^^^
 
+View information about an association in the flux-accounting database.
+
+See :man1:`flux-account-view-user` for more details.
+
 add-user
 ^^^^^^^^
 
+Add an association to the flux-accounting database.
+
+See :man1:`flux-account-add-user` for more details.
+
 delete-user
 ^^^^^^^^^^^
 
+Deactivate an association in the flux-accounting database.
+
+See :man1:`flux-account-delete-user` for more details.
+
 edit-user
 ^^^^^^^^^
 
+Modify an attribute for an association in the flux-accounting database.
+
+See :man1:`flux-account-edit-user` for more details.
+
 BANK ADMINISTRATION
 ===================
 

doc/manpages.py

@@ -45,6 +45,34 @@
         [author],
         1,
     ),
+    (
+        "man1/flux-account-view-user",
+        "flux-account-view-user",
+        "view information about a user in the flux-accounting database",
+        [author],
+        1,
+    ),
+    (
+        "man1/flux-account-add-user",
+        "flux-account-add-user",
+        "add an association to the association_table",
+        [author],
+        1,
+    ),
+    (
+        "man1/flux-account-delete-user",
+        "flux-account-delete-user",
+        "deactivate an association in the flux-accounting database",
+        [author],
+        1,
+    ),
+    (
+        "man1/flux-account-edit-user",
+        "flux-account-edit-user",
+        "modify an attribute for an association in the flux-accounting database",
+        [author],
+        1,
+    ),
     (
         "man5/flux-config-accounting",
         "flux-config-accounting",

doc/test/spell.en.pws

@@ -544,3 +544,5 @@ MaxNodes
 MaxRunningJobs
 ParentBank
 UserID
+bankA
+parsable