Merge pull request #12689 from jsquyres/pr/v5.0.x/rtd-updates

v5.0.x: Read The Docs updates

Author: wenduwan

docs/Makefile.am

@@ -881,7 +881,14 @@ ALL_MAN_BUILT = \
 # built HTML and man docs into a separate location that is included in
 # the tarball.  This gives users a fully copy of the docs included in
 # distribution tarballs.
-html: $(ALL_MAN_BUILT)
+#
+# Note: we name this "html-local" because otherwise Automake issues a
+# warning about us overriding its default "html" target.  In our
+# particular use case, the rules generated if we name this target
+# "html-local" instead of "html" are effectively equivalent to when we
+# name this target "html", so we might as well avoid the Automake
+# warning.
+html-local: $(ALL_MAN_BUILT)
 	$(OMPI_V_COPYALL) rm -rf html; cp -rp $(OUTDIR)/html .
 
 man: $(ALL_MAN_BUILT)

docs/conf.py

@@ -37,10 +37,10 @@ def read_version_file(path):
     if not os.path.exists(path):
         print(f"ERROR: Unable to find file {path}")
         exit(1)
-        
+
     with open(path) as fp:
         version_lines = fp.readlines()
-    
+
     data = dict()
     for line in version_lines:
         if '#' in line:
@@ -129,6 +129,15 @@ def get_tarball_version(path, expr):
 if key in os.environ and os.environ[key] == 'True':
     print("OMPI: found ReadTheDocs build environment")
 
+    # Tell Jinja2 templates the build is running on Read the Docs
+    if "html_context" not in globals():
+        html_context = {}
+    html_context["READTHEDOCS"] = True
+
+    # Define the canonical URL if you are using a custom domain on
+    # Read the Docs
+    html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
     rtd_v = os.environ['READTHEDOCS_VERSION']
     if os.environ['READTHEDOCS_VERSION_TYPE'] == 'external':
         # Make "release" be shorter than the full "ompi_ver" value.