WIP PROTOTYPE/PROPOSAL

Move "big" explanations into the "main" PRRTE RST docs, and have
show_help / man pages mainly be listings of CLI options/values.

Signed-off-by: Jeff Squyres <[email protected]>

configure.ac

@@ -1002,7 +1002,7 @@ AC_CONFIG_FILES([
     docs/Makefile
     src/docs/Makefile
     src/docs/show-help-files/Makefile
-    src/docs/included-content/Makefile
+    src/docs/prrte-rst-content/Makefile
 ])
 
 PRTE_CONFIG_FILES

docs/Makefile.am

@@ -36,6 +36,9 @@ SPHINX_OPTS       ?= -W --keep-going -j auto
 # However, it is necessary to list $(srcdir) when using wildcards.
 RST_SOURCE_FILES = \
         $(srcdir)/*.rst \
+        $(srcdir)/prrte-rst-content/*.rst \
+        $(srcdir)/placement/*.rst \
+        $(srcdir)/hosts/*.rst \
         $(srcdir)/developers/*.rst \
         $(srcdir)/man/*.rst \
         $(srcdir)/man/man1/*.rst \

docs/hosts/cli.rst

@@ -0,0 +1,36 @@
+.. _hosts-cli-label:
+
+Listing Hosts on the Command Line
+=================================
+
+Many PRRTE commands accept the ``--host`` CLI parameter.
+``--host`` accepts a comma-delimited list of tokens of the form:
+
+.. code::
+
+   host[:slots]
+
+The ``host`` token can be either:
+
+* A name that resolves to an IP address, or
+* An IP address
+
+.. note:: The names and/or IP addresses of hosts are *only* used for
+          identifying the target host on which to launch.  They are
+          *not* used for determining which network interfaces are used
+          by applications (e.g., MPI or other network-based
+          applications).
+
+          For network-based applications, consult their documentation
+          for how to specify which network interfaces are used.
+
+The optional integer ``:slots`` parameter tells PRRTE the maximum
+number of slots to use on that host (:ref:`see this section
+<placement-definition-of-slot-label>` for a description of what a
+"slot" is).
+
+For example:
+
+.. code::
+
+   prterun --host node1:10,node2,node3:5 ...

docs/hosts/hostfiles.rst

@@ -0,0 +1,41 @@
+Hostfiles
+=========
+
+Hostfiles (sometimes called "machine files") are a combination of two
+things:
+
+#. A listing of hosts on which to launch processes.
+#. Optionally, limit the number of processes which can be launched on
+   each host.
+
+Syntax
+------
+
+Hostfile syntax consists of one node name on each line, optionally
+including a designated number of "slots":
+
+.. code:: sh
+
+   # This is a comment line, and will be ignored
+   node01  slots=10
+   node13  slots=5
+
+   node15
+   node16
+   node17  slots=3
+   ...
+
+Blank lines and lines beginning with a ``#`` are ignored.
+
+A "slot" is the PRRTE term for an allocatable unit where we can launch
+a process.  :ref:`See this section
+<placement-definition-of-slot-label>` for a longer description of
+slots.
+
+In the absence of the ``slot`` parameter, PRRTE will assign either the
+number of slots to be the number of CPUs detected on the node or the
+resource manager-assigned value if operating in the presence of an
+RM.
+
+.. important:: If using a resource manager, the user-specified number
+               of slots is capped by the RM-assigned value.

docs/hosts/index.rst

@@ -0,0 +1,19 @@
+Host specification
+==================
+
+PRRTE identifies hosts on which to launch processes by:
+
+#. A Resource Manager (RM) telling PRRTE which hosts to use
+#. The user providing a hostfile (also sometimes called a "machine
+   file")
+#. The user providing a list of hosts on the command line
+
+The sections below describe each of these in more detail.
+
+.. toctree::
+   :maxdepth: 1
+
+   rm
+   hostfiles
+   cli
+   relative-indexing

src/docs/included-content/common-schizo-relative-indexing.rst → docs/hosts/relative-indexing.rst

@@ -1,3 +1,6 @@
+Relative host indexing
+======================
+
 Hostfile and ``--host`` specifications can also be made using relative
 indexing. This allows a user to stipulate which hosts are to be used
 for a given app context without specifying the particular host name,

docs/hosts/rm.rst

@@ -0,0 +1,9 @@
+Resource Manager-Provided Hosts
+===============================
+
+When launching under a Resource Manager (RM), the RM usually
+picks which hosts |mdash| and how many processes can be launched on
+each host |mdash| on a per-job basis.
+
+The RM will communicate this information to PRRTE directly; users can
+simply omit specifying hosts or numbers of processes.

docs/index.rst

@@ -4,10 +4,20 @@ PMIx Reference Runtime Environment (PRRTE) |prte_ver|
 The project is formally referred to in documentation by "PRRTE", and
 the GitHub repository is ``prrte``.
 
-However, we have found that most users do not like typing the two
-consecutive ``r`` letters in the name. Hence, all of the internal API symbols,
-environment variables, MCA frameworks, and CLI executables all use the
-abbreviated ``prte`` (one ``r``, not two) for convenience.
+.. note:: We have found that most users do not like typing the two
+          consecutive ``r`` letters in the name. Hence, all of the
+          internal API symbols, environment variables, MCA frameworks,
+          and CLI executables all use the abbreviated ``prte`` (one
+          ``r``, not two) for convenience.
+
+Documentation locations
+=======================
+
+This documentation can be found in the following locations:
+
+* On the web: https://docs.prrte.org/
+* In the tarball: ``docs/_build/html/index.html``
+* Installed: ``$prefix/share/doc/prrte/html/index.html``
 
 Table of contents
 =================
@@ -21,6 +31,10 @@ Table of contents
    getting-help
    install
    configuration
+   hosts/index
+   placement/index
+   notifications
+   session-directory
    resilience
    developers/index
    contributing