docs: Render C/F90/F08 bindings in man pages

Use the pympistandard Python module and associated MPI-4.1 MPI
Standard JSON definition file to generate bindings -- regular and
embiggened -- in the MPI man pages.

In the generation code, had to handle a variety of cases:

* When there is no C binding
* When there is no mpif.h / use mpi binding
* When there is no use mpi_f08 binding
* When there are embiggened C and/or F08 bindings
* When a single man page includes documentation for multiple MPI APIs
* When we do not have man pages for MPI APIs described in the official
  MPI Forum API JSON

Also, this commit adds a new submodule: the pympistandard Python
module from the MPI Forum repository.

Some other cleanups were also necessary as part of this commit:

* Add some missing man pages
* Fix some random RST formatting errors in existing man pages

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

Author: jsquyres

.gitignore

@@ -516,6 +516,7 @@ docs/_build
 docs/_static
 docs/_static/css/custom.css
 docs/_templates
+docs/man-openmpi/man3/bindings
 
 # Common Python virtual environment and cache directory names
 venv

.gitmodules

@@ -9,3 +9,6 @@
 [submodule "oac"]
 	path = config/oac
 	url = ../../open-mpi/oac
+[submodule "3rd-party/pympistandard"]
+	path = 3rd-party/pympistandard
+	url = ../../mpi-forum/pympistandard

.readthedocs-pre-create-environment.sh

@@ -26,3 +26,6 @@ PRRTE_RST_TARGET_DIR=docs/prrte-rst-content
 
 cp -rp $SCHIZO_SRC_DIR $SCHIZO_TARGET_DIR
 cp -rp $PRRTE_RST_SRC_DIR $PRRTE_RST_TARGET_DIR
+
+cd docs
+python3 ./generate-mpi-man3-bindings.py --srcdir . --builddir .

3rd-party/Makefile.am

@@ -1,6 +1,7 @@
 #
 # Copyright (c) 2020      Amazon.com, Inc. or its affiliates.
 #                         All Rights reserved.
+# Copyright (c) 2025      Jeffrey M. Squyres.  All rights reserved.
 # $COPYRIGHT$
 #
 # Additional copyrights may follow
@@ -16,7 +17,7 @@
 
 SUBDIRS = $(OPAL_3RDPARTY_SUBDIRS)
 DIST_SUBDIRS = $(OPAL_3RDPARTY_DIST_SUBDIRS)
-EXTRA_DIST =  $(OPAL_3RDPARTY_EXTRA_DIST) autogen.subdirs
+EXTRA_DIST =  $(OPAL_3RDPARTY_EXTRA_DIST) autogen.subdirs pympistandard
 
 distclean-local:
 	rm -rf $(OPAL_3RDPARTY_DISTCLEAN_DIRS)
@@ -26,3 +27,12 @@ check:
 
 check-recursive:
 	@echo "auto-recursing into 3rd-party packages for check disabled"
+
+# We recursively copied the pympystandard directory.  As suggested by
+# the Automake docs (see section 14.3, "The dist Hook"), use the
+# dist-hook target to delete a bunch of extra stuff that we might have
+# copied.
+dist-hook:
+	@find $(distdir)/pympistandard -name __pycache__ -exec rm -rf {} \; || :
+	@find $(distdir)/pympistandard -name \*.pyc -exec rm -rf {} \; || :
+	@rm -rf $(distdir)/pympistandard/.git

3rd-party/pympistandard

@@ -1,6 +1,6 @@
 #
 # Copyright (c) 2022 Cisco Systems, Inc.  All rights reserved.
-# Copyright (c) 2023-2024 Jeffrey M. Squyres.  All rights reserved.
+# Copyright (c) 2023-2025 Jeffrey M. Squyres.  All rights reserved.
 #
 # $COPYRIGHT$
 #
@@ -60,6 +60,8 @@ RST_SOURCE_FILES   = \
 EXTRA_DIST         = \
         requirements.txt \
         no-prrte-content.rst.txt \
+        generate-mpi-man3-bindings.py \
+        mpi-standard-apis.json \
         html \
         man \
         $(SPHINX_CONFIG) \
@@ -845,6 +847,10 @@ OMPI_MAN3_RST = $(OMPI_MAN3:%.3=man-openmpi/man3/%.3.rst)
 OMPI_MAN3_BUILT = $(OMPI_MAN3:%.3=$(MAN_OUTDIR)/%.3)
 OMPI_MAN3_INSTALL_FROM = $(OMPI_MAN3:%.3=$(MAN_INSTALL_FROM)/%.3)
 
+# Use this one file as a sentinel for building all the Open MPI man
+# page API bindings files
+SENTINEL_OMPI_MAN3_BINDING = $(builddir)/man-openmpi/man3/bindings/mpi_init.rst
+
 OMPI_MAN7_RST = $(OMPI_MAN7:%.7=man-openmpi/man7/%.7.rst)
 OMPI_MAN7_BUILT = $(OMPI_MAN7:%.7=$(MAN_OUTDIR)/%.7)
 OMPI_MAN7_INSTALL_FROM = $(OMPI_MAN7:%.7=$(MAN_INSTALL_FROM)/%.7)
@@ -923,7 +929,7 @@ man: $(ALL_MAN_BUILT)
 # Remove the copies of the built HTML and man pages to get back to a
 # clean git clone.
 maintainer-clean-local:
-	rm -rf html man
+	rm -rf html man man-openmpi/man3/bindings
 
 # If we're doing a VPATH build, we may have "html" and "man"
 # directories in the build tree (e.g., if we did "make dist").  Remove
@@ -969,8 +975,8 @@ $(builddir)/schizo-ompi-rst-content:
 $(builddir)/prrte-rst-content:
 	$(OMPI_V_MKDIR) if test ! -d "$@"; then mkdir "$@"; fi
 
-# Get the schizo-ompi-rst-cli.rst file that we need.  CAVEAT: we name
-# it ".in" so that Sphinx doesn't slurp it in via two different
+# Get the schizo-ompi-cli.rst file that we need.  CAVEAT: we name it
+# ".rstxt" so that Sphinx doesn't slurp it in via two different
 # locations in the RST docroot (i.e., via
 # /schizo-ompi-rst-content/schizo-ompi-cli.rstxt and via
 # /man-openmpi/man1/mpirun.1.rst).  Sphinx *shouldn't* do this -- it
@@ -1000,10 +1006,20 @@ $(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt: $(srcdir)/no-prrte-co
 	cp -pf $(srcdir)/no-prrte-content.rst.txt "$@"
 endif
 
+$(builddir)/man-openmpi/man3/bindings:
+	$(OMPI_V_MKDIR) if test ! -d "$@"; then mkdir -p "$@"; fi
+
+$(SENTINEL_OMPI_MAN3_BINDING): $(builddir)/man-openmpi/man3/bindings
+$(SENTINEL_OMPI_MAN3_BINDING): generate-mpi-man3-bindings.py
+$(SENTINEL_OMPI_MAN3_BINDING): mpi-standard-apis.json
+	$(OMPI_V_GEN) $(PYTHON3) $(srcdir)/generate-mpi-man3-bindings.py \
+		--srcdir $(srcdir) --builddir $(builddir)
+
 $(ALL_MAN_BUILT): $(builddir)/prrte-rst-content
 $(ALL_MAN_BUILT): $(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt
 $(ALL_MAN_BUILT): $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES)
 $(ALL_MAN_BUILT): $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG)
+$(ALL_MAN_BUILT): $(SENTINEL_OMPI_MAN3_BINDING)
 
 # Render the RST source into both 1) full HTML docs and 2) nroff man
 # pages.
@@ -1031,7 +1047,7 @@ $(ALL_MAN_BUILT): $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG)
 # not think of anything better to do.
 #
 # NOTE: This is a little gross in that for a VPATH build, we *always*
-# copy from the source tree to the dest tree (if the target does not
+# copy from the source tree to the build tree (if the target does not
 # exist or any of the sources in the source tree -- thanks to
 # make/VPATH handling -- have changed compared to the target).
 # However, we're using "cp -p", so even though we're copying *all the
@@ -1041,6 +1057,7 @@ $(ALL_MAN_BUILT): $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG)
 # changed.  We're going to overwrite any local changes in the build
 # tree, but you shouldn't be editing the build tree, anyway.  So --
 # good enough.
+
 $(ALL_MAN_BUILT):
 	$(OMPI_V_SPHINX_COPYRST) if test "$(srcdir)" != "$(builddir)"; then \
 	    len=`echo "$(srcdir)/" | wc -c`; \