Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Revamp prterun show_help files to integrate with Sphinx
This commit represents a major reorganization and revamp of prterun's
show_help files. The overriding purpose is to allow downstream
projects -- such as MPI implementations -- to include PRRTE's Sphinx
(.rst) documentation in their own.
This entailed the following:
* The existing "show help" .txt files are used by the existing "<cmd>
--help <topic>" CLI system. It was important to preserve this CLI
capability.
* However, we wanted this same content to also appear in various man
pages (and therefore also HTML documentation). Hence, we moved the
existing "show_help" .txt files to a new location: src/docs/
(vs. docs/, where the main PRRTE documentation lives).
* After various experiments, we determined that we just could not
have both the main PRRTE Sphinx docs and this new class of
show_help/man-page-content combination docs in the same Sphinx
docs tree. The structure and layout of how we need to render
these two sets of docs are quite different.
Instead, as described below, we took a different approach: have
"building blocks" of content that can be assembled in different
ways that are ultimately rendered with the structure and layout
required for each environment.
* src/docs/ contains 2 directories:
* prrte-rst-content: this directory contains a README.txt file that
both PRRTE docs authors and downstream consumers of the RST
content should read. It explains how both how to author/maintain
the docs in that directory, as well as how to integrate the
contents of this directory into downstream project RST docroots,
and how to include the content.
Essentially, this directory is the main source of prterun CLI
documentation content. Each topic is split into its own file (see
the README for more info) so that it can be RST-included in other
.rst files as relevant. Think of these files as individual
building blocks of content that can be assembled in multiple
different ways.
The text content in this directory is mostly content from previous
show_help-style text files moved into this directory, split into
individual .rst files, and then converted to RST syntax. Some of
the tables ended up being nicer / easier to maintain, for example.
* show-help-files: the contents of this directory are rendered to
what ultimately become the "show_help" text files.
This directory effectively RST-includes the files from the
prrte-rst-content directory into files and renders them as
INI-style "show_help" text files (i.e., suitable for reading by
the prte_show_help() subsystem).
* The src/docs/prrte-rst-content is also RST-included in the top-level
docs/ .rst files (va a sym link). That allows the same "building
blocks" of documentation content to be included in both the
show_help files and the HTML/man pages.
* Note that in distribution tarballs, pre-built HTML docs, norff man
pages, and INI-style "show_help" text files will be included in the
tarball -- end users do not need to have Sphinx available.
For git clones, where none of the Sphinx-generated content is
available (i.e., HTML docs, nroff man pages, show_help text files),
Sphinx is also still not required (but it *is* still required to
"make dist"). If Sphinx is not available when "configure" is
invoked, dummy INI-style "show_help" text files are generated (that
basically say "You don't have Sphinx, so you don't get help here").
That is the overall scheme. There were many other minor points
included in this work, including (but not limited to):
* Moving existing explanations of hosts and hostfiles -- and expanding
on them -- to the main docs.
* Moving explanations of relative indexting to the main docs.
* Moving explanations of notifications to the main docs.
* Moving listing of deprecated CLI options to the main docs.
* Moving explanations of diagnostics to the main docs.
* Moving most process placement explanations and examples to the main
docs.
* Moving explanations of the session directory to the main docs.
* Adding psched.1 and pterm.1 man pages. More work needs to be done
here.
* Slightly improve prte.1, prte_info.1, prted.1, prterun.1, and prun.1
man pages. More work needs to be done here.
It is expected that the text content of all the docs will continue to
be improved over time. The focus of this commit was not to make the
content perfect, but rather to create a first-gen infrastructure for
having a single source of documentation content that can be rendered
by Sphinx in 3 ways (HTML docs, nroff man pages, and show_help files),
and also included in downstream RST documentation.
Signed-off-by: Ralph Castain <rhc@pmix.org>
Signed-off-by: Jeff Squyres <jeff@squyres.com>- Loading branch information
