doc: add man(1) page support, entries for DB administration subcommands

doc/Makefile.am

@@ -2,21 +2,29 @@
 
 SUBDIRS = . test
 
-MAN_FILES = $(MAN5_FILES)
+MAN_FILES = $(MAN1_FILES) $(MAN5_FILES)
 
+MAN1_FILES = $(MAN1_FILES_PRIMARY)
 MAN5_FILES = $(MAN5_FILES_PRIMARY)
 
+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
+
 MAN5_FILES_PRIMARY = \
 	man5/flux-config-accounting.5
 
 RST_FILES  = \
+	$(MAN1_FILES_PRIMARY:.1=.rst) \
 	$(MAN5_FILES_PRIMARY:.5=.rst)
 
 if ENABLE_DOCS
-man_MANS = $(MAN5_FILES)
+man_MANS = $(MAN1_FILES) $(MAN5_FILES)
 endif
 
-SUFFIXES = .rst .5
+SUFFIXES = .rst .1 .5
 
 sphinx_man = $(sphinx_man_$(V))
 sphinx_man_ = $(sphinx_man_$(AM_DEFAULT_VERBOSITY))
@@ -42,7 +50,7 @@ $(MAN_FILES): manpages.py conf.py $(RST_FILES)
 		-m sphinx $(sphinx_verbose_flags) -b man $(srcdir) ./man \
 		$(STDERR_DEVNULL)
 	@echo "  MV        manpages"; \
-	for sec in 5; do \
+	for sec in 1 5; do \
 	  $(MKDIR_P) man$$sec && \
 	  mv -f $(abs_builddir)/man/*.$$sec man$$sec/; \
 	done
@@ -62,6 +70,7 @@ EXTRA_DIST = \
 	requirements.txt \
 	guide/accounting-guide.rst \
 	$(RST_FILES) \
+	man1/index.rst \
 	man5/index.rst
 
 CLEANFILES = \

doc/index_man.rst

@@ -6,4 +6,5 @@ Manual Pages
 .. toctree::
    :maxdepth: 1
 
+   man1/index
    man5/index

doc/man1/flux-account-create-db.rst

@@ -0,0 +1,30 @@
+.. flux-help-section: flux account
+
+=========================
+flux-account-create-db(1)
+=========================
+
+
+SYNOPSIS
+========
+
+**flux** **account** **create-db** [OPTIONS]
+
+DESCRIPTION
+===========
+
+.. program:: flux account create-db
+
+:program:`flux account create-db` creates the flux-accounting SQLite database
+which will hold all of the accounting information for users, banks, queues,
+projects, and job records.
+
+.. option:: --priority-usage-reset-period
+
+   The number of weeks at which job usage information gets reset to 0. By
+   default, the usage reset period is set at 4 weeks.
+
+.. option:: --priority-decay-half-life
+
+    The contribution of historical usage in weeks on the composite job usage
+    value. By default, this is set at 1 week.

doc/man1/flux-account-export-db.rst

@@ -0,0 +1,38 @@
+.. flux-help-section: flux account
+
+=========================
+flux-account-export-db(1)
+=========================
+
+
+SYNOPSIS
+========
+
+**flux** **account** **export-db** [OPTIONS]
+
+DESCRIPTION
+===========
+
+.. program:: flux account export-db
+
+:program:`flux account export-db` will extract flux-accounting database
+information into two ``.csv`` files.
+
+.. option:: -u, --users
+
+    Path to a ``.csv`` file containing user information.
+
+.. option:: -b, --banks
+
+    Path to a ``.csv`` file containing bank information.
+
+The order of columns extracted from the ``association_table``:
+
+**Username,UserID,Bank,Shares,MaxRunningJobs,MaxActiveJobs,MaxNodes,Queues**
+
+The order of columns extracted from the ``bank_table``:
+
+**Bank,ParentBank,Shares**
+
+If no custom path is specified, this will create a file in the current working
+directory called ``users.csv`` and ``banks.csv``.

doc/man1/flux-account-pop-db.rst

@@ -0,0 +1,42 @@
+.. flux-help-section: flux account
+
+======================
+flux-account-pop-db(1)
+======================
+
+
+SYNOPSIS
+========
+
+**flux** **account** **pop-db** [OPTIONS]
+
+DESCRIPTION
+===========
+
+.. program:: flux account pop-db
+
+:program:`flux account pop-db` will populate an already-existing
+flux-accounting database with a ``.csv`` file.
+
+.. option:: -u, --users
+
+    Path to a ``.csv`` file containing user information.
+
+.. option:: -b, --banks
+
+    Path to a ``.csv`` file containing bank information.
+
+The order of elements required for populating the ``association_table`` are as
+follows:
+
+**Username,UserID,Bank,Shares,MaxRunningJobs,MaxActiveJobs,MaxNodes,Queues**
+
+**Shares,MaxRunningJobs,MaxActiveJobs,MaxNodes** can be left blank (``''``) in
+the ``.csv`` file for a given row.
+
+The order of elements required for populating the ``bank_table`` are as
+follows:
+
+**Bank,ParentBank,Shares**
+
+**Shares** can be left blank (``''``) in the ``.csv`` file for a given row.

doc/man1/flux-account.rst

@@ -0,0 +1,121 @@
+.. flux-help-section: flux account
+
+===============
+flux-account(1)
+===============
+
+
+SYNOPSIS
+========
+
+**flux** **account** [*COMMAND*] [OPTIONS]
+
+DESCRIPTION
+===========
+
+.. program:: flux account
+
+:program:`flux account` provides an interface to the SQLite database containing
+information regarding banks, associations, queues, projects, and archived jobs.
+It also provides administrative commands like exporting and populating the DB's
+information to and from ``.csv`` files, updating the database when new versions
+of flux-accounting are released, and more.
+
+DATABASE ADMINISTRATION
+=======================
+
+create-db
+^^^^^^^^^
+
+Create the flux-accounting database.
+
+See :man1:`flux-account-create-db` for more details.
+
+pop-db
+^^^^^^
+
+Populate a flux-accounting database with ``.csv`` files.
+
+See :man1:`flux-account-pop-db` for more details.
+
+export-db
+^^^^^^^^^
+
+Export a flux-accounting database into ``.csv`` files.
+
+See :man1:`flux-account-export-db` for more details.
+
+USER ADMINISTRATION
+===================
+
+view-user
+^^^^^^^^^
+
+add-user
+^^^^^^^^
+
+delete-user
+^^^^^^^^^^^
+
+edit-user
+^^^^^^^^^
+
+BANK ADMINISTRATION
+===================
+
+view-bank
+^^^^^^^^^
+
+add-bank
+^^^^^^^^
+
+delete-bank
+^^^^^^^^^^^
+
+edit-bank
+^^^^^^^^^
+
+list-banks
+^^^^^^^^^^
+
+QUEUE ADMINISTRATION
+====================
+
+view-queue
+^^^^^^^^^^
+
+add-queue
+^^^^^^^^^
+
+delete-queue
+^^^^^^^^^^^^
+
+edit-queue
+^^^^^^^^^^
+
+PROJECT ADMINISTRATION
+======================
+
+view-project
+^^^^^^^^^^^^
+
+add-project
+^^^^^^^^^^^
+
+delete-project
+^^^^^^^^^^^^^^
+
+list-projects
+^^^^^^^^^^^^^
+
+JOB RECORDS
+===========
+
+view-job-records
+^^^^^^^^^^^^^^^^
+
+update-usage
+^^^^^^^^^^^^
+
+scrub-old-jobs
+^^^^^^^^^^^^^^

doc/man1/index.rst

@@ -0,0 +1,8 @@
+Section 1 - Flux Accounting Commands
+====================================
+
+.. toctree::
+  :maxdepth: 1
+  :glob:
+
+  *

doc/manpages.py

@@ -17,6 +17,34 @@
 # - Author (use [author])
 # - Manual section
 man_pages = [
+    (
+        "man1/flux-account",
+        "flux-account",
+        "flux-accounting commands",
+        [author],
+        1,
+    ),
+    (
+        "man1/flux-account-create-db",
+        "flux-account-create-db",
+        "create the flux-accounting SQLite database",
+        [author],
+        1,
+    ),
+    (
+        "man1/flux-account-pop-db",
+        "flux-account-pop-db",
+        "populate a flux-accounting database with .csv files",
+        [author],
+        1,
+    ),
+    (
+        "man1/flux-account-export-db",
+        "flux-account-export-db",
+        "export flux-accounting database information into .csv files",
+        [author],
+        1,
+    ),
     (
         "man5/flux-config-accounting",
         "flux-config-accounting",

doc/test/spell.en.pws

@@ -536,3 +536,11 @@ raiseall
 fairshare
 dne
 DNE
+csv
+SQLite
+DB's
+MaxActiveJobs
+MaxNodes
+MaxRunningJobs
+ParentBank
+UserID