Update documentation for web page

docs/source/geopmaccess.1.rst

@@ -5,6 +5,13 @@ geopmaccess(1) -- Access management for the GEOPM Service
 Synopsis
 --------
 
+.. code-block:: none
+
+    geopmaccess [-h] [-v] [-c] [-u | -g GROUP | -a | -l | -s] [-w | -e | -D] [-n | -F] [-x]
+
+Access management for the GEOPM Service. Command line tool for reading and
+writing the access management lists for the GEOPM Service signals and controls.
+
 Read Access List
 ~~~~~~~~~~~~~~~~
 
@@ -33,7 +40,6 @@ Remove Access List
 
     geopmaccess -D [-c] [-g GROUP]
 
-
 Get Help or Version
 ~~~~~~~~~~~~~~~~~~~
 
@@ -45,33 +51,73 @@ Get Help or Version
 Description
 -----------
 
-The GEOPM service uses the ``/etc/geopm`` directory to store
-files that control which signals and controls may be accessed by a
-user through the service.  The purpose of the ``geopmaccess`` command
-line tool is to enable reading and writing of these access list files.
+The GEOPM service uses the ``/etc/geopm`` directory to store files that control
+which signals and controls may be accessed by a user through the service.  The
+purpose of the ``geopmaccess`` command line tool is to enable reading and
+writing of these access list files.
 
 
 Options
 ~~~~~~~
--c, --controls  Command applies to controls not signals
--u, --default   Print the default user access list
--g, --group     Read or write the access list for a specific Unix GROUP
--a, --all       Print all signals or controls supported by the service system
--w, --write     Use standard input to write an access list
--e, --edit      Edit an access list using EDITOR environment variable, default
-                ``vi``
--D, --delete    Remove an access list for default user or a particular Unix Group
--n, --dry-run   Do error checking on all user input, but do not modify
-                configuration files
--F, --force     Write access list without validating GEOPM Service support for
-                names
--l, --log       Print a log of all signals or controls that have been accessed
-                since the service was last restarted.
--s, --msr-safe  Print the minimal msr-safe allowlist required by GEOPM.
--h, --help      Print brief summary of the command line usage information, then
-                exit
--v, --version   Print version of :doc:`geopm(7) <geopm.7>` to standard output,
-                then exit
+
+-h, --help  .. _help option:
+
+    Print help message and exit
+
+-v, --version  .. _version option:
+
+    Print version and exit
+
+-c, --controls  .. _controls option:
+
+    Command applies to controls not signals
+
+-u, --default  .. _default option:
+
+    Print the default user access list
+
+-g GROUP, --group GROUP  .. _group option:
+
+    Read or write the access list for a specific Unix GROUP
+
+-a, --all  .. _all option:
+
+    Print all signals or controls supported by the service system
+
+-l, --log  .. _log option:
+
+    Print list of used signals or controls used since last restart of the
+    service
+
+-s, --msr-safe  .. _msr-safe option:
+
+    Generate an allowlist for msr-safe
+
+-w, --write  .. _write option:
+
+    Use standard input to write an access list. Implies -u unless -g is
+    provided.
+
+-e, --edit  .. _edit option:
+
+    Edit an access list using EDITOR environment variable, default vi
+
+-D, --delete  .. _delete option:
+
+    Remove an access list for default user or a particular Unix Group
+
+-n, --dry-run  .. _dry-run option:
+
+    Do error checking on all user input, but do not modify configuration files
+
+-F, --force  .. _force option:
+
+    Write access list without validating GEOPM Service support for names
+
+-x, --direct  .. _direct option:
+
+    Write directly to files, do not use DBus
+
 
 Query Access
 ~~~~~~~~~~~~

docs/source/geopmsession.1.rst

@@ -5,6 +5,14 @@ geopmsession(1) -- Command line interface for the GEOPM service batch read featu
 Synopsis
 --------
 
+.. code-block:: none
+
+    geopmsession [-h] [-v] [-t TIME] [-p PERIOD] [--pid PID] [--print-header]
+
+Command line interface for the geopm service batch read features. This command
+can be used to read signals by opening a session with the geopm service.
+
+
 Read a signal
 ~~~~~~~~~~~~~
 
@@ -49,11 +57,33 @@ signals requested though standard input is made and the results are
 printed to the screen.
 
 Options
-~~~~~~~
--h, --help                  show this help message and exit
--t TIME, --time TIME        Total run time of the session to be opened in seconds
--p PERIOD, --period PERIOD  When used with a read mode session reads all values
-                            out periodically with the specified period in seconds
+-------
+
+-h, --help  .. _help option:
+
+    Print help message and exit
+
+-v, --version  .. _version option:
+
+    Print version and exit
+
+-t TIME, --time TIME  .. _time option:
+
+    Total run time of the session to be opened in seconds
+
+-p PERIOD, --period PERIOD  .. _period option:
+
+    When used with a read mode session reads all values out periodically with
+    the specified period in seconds
+
+--pid PID  .. _pid option:
+
+    Stop the session when the given process PID ends
+
+--print-header  .. _header option:
+
+    Print a CSV header before printing any sampled values
+
 
 Examples
 --------

docs/source/overview.rst

@@ -794,61 +794,61 @@ option to ``geopmlaunch``.  For more information about ``geompmlaunch`` see:
 :doc:`geopmlaunch.1`.  For more information about the reports, see:
 :doc:`geopm_report.7`.
 
-Profiling Non-MPI Applications
-""""""""""""""""""""""""""""""
 
-The ``geopmlaunch(1)`` command may not be best suited for your needs
-if you are running a non-MPI application, or if you are running an MPI
-application but the launch command is embedded in scripts that are
-difficult to modify.  Instead of using ``geopmlaunch(1)``, the
-user may use the ``geopmctl(1)`` application in conjunction with
-environment variables that control the GEOPM Runtime behavior.
-
-In this simple example we run the ``sleep(1)`` command for 10 seconds
-and monitor the system during its execution.  Rather than using the
-``geopmlaunch`` tool as in the above example, we will run the
-``geopmctl`` command in the background while the application of
-interest is executing.  There are four requirements to enable the
-GEOPM controller process to connect to the application process and
-generate a report:
-
-1. Both the ``geopmctl`` process and the application process must have
-   the ``GEOPM_PROFILE`` environment variable set to the **same**
-   value or both environments may leave this variable unset.
-2. The application process must have ``LD_PRELOAD=libgeopm.so.2`` set
-   in the environment or the application binary must be linked
-   directly to ``libgeopm.so.2`` at compile time.
-3. The ``GEOPM_REPORT`` environment variable must be set in the
-   environment of the ``geopmctl`` process.
-4. The ``GEOPM_PROGRAM_FILTER`` environment variable is required and
-   explicitly lists the program invovation names of any process to be
-   profiled. All other programs will not be affected by ``LD_PRELOAD``
-   of ``libgeopm.so``.  For this reason a user will typically set
-   these two environment variables together.  This is especially
-   important when profiling programs within a bash script.
-
-In addition to generating a report in YAML format, the example below
-showcases two optional features of the GEOPM Runtime:
-
-1. **CSV Trace File**: By setting the ``GEOPM_TRACE`` environment
-   variable, you can generate a trace file in CSV format.
+Profiling Applications without ``geopmlaunch``
+""""""""""""""""""""""""""""""""""""""""""""""
+
+The ``geopmlaunch(1)`` command may not be best suited for your needs if you are
+running a non-MPI application, or if you are running an MPI application but the
+launch command is embedded in scripts that are difficult to modify.  Instead of
+using ``geopmlaunch(1)``, the user may use the ``geopmctl(1)`` application in
+conjunction with environment variables that control the GEOPM Runtime behavior.
+
+In this simple example we run the ``sleep(1)`` command for 10 seconds and
+monitor the system during its execution.  Rather than using the ``geopmlaunch``
+tool as in the above example, we will run the ``geopmctl`` command in the
+background while the application of interest is executing.  The ``geopmctl`` MPI
+application should be launched with one process per compute node when executing
+the runtime on multiple nodes.  There are five requirements to enable the GEOPM
+controller process to connect to the application process and generate a report:
+
+1. Both the ``geopmctl`` process and the application process must have the
+   ``GEOPM_PROFILE`` environment variable set to the **same** value or both
+   environments may leave this variable unset.
+2. The application process must have ``LD_PRELOAD=libgeopm.so.2`` set in the
+   environment or the application binary must be linked directly to
+   ``libgeopm.so.2`` at compile time.
+3. The ``GEOPM_REPORT`` environment variable must be set in the environment of
+   the ``geopmctl`` process.
+4. The ``GEOPM_PROGRAM_FILTER`` environment variable is required and explicitly
+   lists the program invocation names of any process to be profiled. All other
+   programs will not be affected by ``LD_PRELOAD`` of ``libgeopm.so``.  For this
+   reason a user will typically set these two environment variables together.
+   This is especially important when profiling programs within a bash script.
+5. The ``GEOPM_NUM_PROCESS`` variable must be set in the ``geopmctl``
+   environment if there is more than one process to be tracked on each compute
+   node.
+
+In addition to generating a report in YAML format, the example below showcases
+two optional features of the GEOPM Runtime:
+
+1. **CSV Trace File**: By setting the ``GEOPM_TRACE`` environment variable, you
+   can generate a trace file in CSV format.
 2. **Sampling Period Adjustment**: The ``GEOPM_PERIOD`` environment variable
    allows you to modify the controller's sampling period. For instance, setting
    it to 200 milliseconds, up from the default 5 milliseconds, results in
    approximately 50 rows of samples in the trace file (calculated as five
    samples per second over ten seconds).
-3. **Disable Network Use** The ``GEOPM_CTL_LOCAL`` environment
-   variable may be set which disables all intra-node communication
-   between the controllers on each node, thereby generating a unique
-   report file per host node over which the application processes are
-   launched.
+3. **Disable Network Use** The ``GEOPM_CTL_LOCAL`` environment variable may be
+   set which disables all intra-node communication between the controllers on
+   each node, thereby generating a unique report file per host node over which
+   the application processes are launched.
 
 These three options together will inform the GEOPM runtime controller
-(``geopmctl``) to profile the ``sleep`` utility and generate a CSV trace
-file with approximately 50 rows of samples (five per-second for ten seconds).
-In the provided example, the ``awk`` command extracts specific columns: time
-since application start (column 1), CPU energy (column 6), and CPU power
-(column 8).
+(``geopmctl``) to profile the ``sleep`` utility and generate a CSV trace file
+with approximately 50 rows of samples (five per-second for ten seconds).  In the
+provided example, the ``awk`` command extracts specific columns: time since
+application start (column 1), CPU energy (column 6), and CPU power (column 8).
 
 .. code-block:: bash