From 6d1d2c358182114fb68ee7c411d08c7efd5f0629 Mon Sep 17 00:00:00 2001 From: Christopher Moussa Date: Thu, 21 Nov 2024 13:35:48 -0800 Subject: [PATCH 1/2] doc: add infrastructure for man(1) pages Problem: flux-accounting has no support for adding man(1) pages to the project, which is needed for man pages for all of the various flux-accounting commands. Add a man1/ folder to flux-accounting to allow man(1) pages to be added to the repository. --- doc/Makefile.am | 17 +++++++++++++---- doc/index_man.rst | 1 + doc/man1/index.rst | 8 ++++++++ 3 files changed, 22 insertions(+), 4 deletions(-) create mode 100644 doc/man1/index.rst diff --git a/doc/Makefile.am b/doc/Makefile.am index 2691a3354..c262ffd42 100644 --- a/doc/Makefile.am +++ b/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 = \ diff --git a/doc/index_man.rst b/doc/index_man.rst index 21e47d272..b01e3cc80 100644 --- a/doc/index_man.rst +++ b/doc/index_man.rst @@ -6,4 +6,5 @@ Manual Pages .. toctree:: :maxdepth: 1 + man1/index man5/index \ No newline at end of file diff --git a/doc/man1/index.rst b/doc/man1/index.rst new file mode 100644 index 000000000..6c51a802a --- /dev/null +++ b/doc/man1/index.rst @@ -0,0 +1,8 @@ +Section 1 - Flux Accounting Commands +==================================== + +.. toctree:: + :maxdepth: 1 + :glob: + + * From ad3e1ba0604ab5a61d0b95a9673c216697f51849 Mon Sep 17 00:00:00 2001 From: Christopher Moussa Date: Thu, 21 Nov 2024 13:38:39 -0800 Subject: [PATCH 2/2] man1: add man(1) for flux-account, DB admin cmds Problem: flux-accounting doesn't have a man(1) entry for flux-account, which has lots of subcommands that could use specific manual pages to describe how to use each subcommand. Add a general flux-account(1) man page entry and list of all the currently available subcommands. Add man(1) entries for all of the DB administration commands, i.e create-db, export-db, and pop-db. Add some of the flagged "mispelled" words in these man pages to the dictionary. --- doc/man1/flux-account-create-db.rst | 30 +++++++ doc/man1/flux-account-export-db.rst | 38 +++++++++ doc/man1/flux-account-pop-db.rst | 42 ++++++++++ doc/man1/flux-account.rst | 121 ++++++++++++++++++++++++++++ doc/manpages.py | 28 +++++++ doc/test/spell.en.pws | 8 ++ 6 files changed, 267 insertions(+) create mode 100644 doc/man1/flux-account-create-db.rst create mode 100644 doc/man1/flux-account-export-db.rst create mode 100644 doc/man1/flux-account-pop-db.rst create mode 100644 doc/man1/flux-account.rst diff --git a/doc/man1/flux-account-create-db.rst b/doc/man1/flux-account-create-db.rst new file mode 100644 index 000000000..39392a1ce --- /dev/null +++ b/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. diff --git a/doc/man1/flux-account-export-db.rst b/doc/man1/flux-account-export-db.rst new file mode 100644 index 000000000..48295793a --- /dev/null +++ b/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``. diff --git a/doc/man1/flux-account-pop-db.rst b/doc/man1/flux-account-pop-db.rst new file mode 100644 index 000000000..f71544328 --- /dev/null +++ b/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. diff --git a/doc/man1/flux-account.rst b/doc/man1/flux-account.rst new file mode 100644 index 000000000..378ba613b --- /dev/null +++ b/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 +^^^^^^^^^^^^^^ diff --git a/doc/manpages.py b/doc/manpages.py index bcfbc5733..cdc9c1df0 100644 --- a/doc/manpages.py +++ b/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", diff --git a/doc/test/spell.en.pws b/doc/test/spell.en.pws index 22176b312..e5e8ab575 100644 --- a/doc/test/spell.en.pws +++ b/doc/test/spell.en.pws @@ -536,3 +536,11 @@ raiseall fairshare dne DNE +csv +SQLite +DB's +MaxActiveJobs +MaxNodes +MaxRunningJobs +ParentBank +UserID