DOC/CI: Fix building docs with --no-api (#38858)

rhshadrach · web-flow · commit cca4901bb477 · 2021-01-13T15:30:20.000+01:00
diff --git a/doc/make.py b/doc/make.py
@@ -46,6 +46,7 @@ def __init__(
         warnings_are_errors=False,
     ):
         self.num_jobs = num_jobs
+        self.include_api = include_api
         self.verbosity = verbosity
         self.warnings_are_errors = warnings_are_errors
 
@@ -188,7 +189,14 @@ def _add_redirects(self):
                 if not row or row[0].strip().startswith("#"):
                     continue
 
-                path = os.path.join(BUILD_PATH, "html", *row[0].split("/")) + ".html"
+                html_path = os.path.join(BUILD_PATH, "html")
+                path = os.path.join(html_path, *row[0].split("/")) + ".html"
+
+                if not self.include_api and (
+                    os.path.join(html_path, "reference") in path
+                    or os.path.join(html_path, "generated") in path
+                ):
+                    continue
 
                 try:
                     title = self._get_page_title(row[1])
@@ -198,11 +206,6 @@ def _add_redirects(self):
                     # sphinx specific stuff
                     title = "this page"
 
-                if os.path.exists(path):
-                    raise RuntimeError(
-                        f"Redirection would overwrite an existing file: {path}"
-                    )
-
                 with open(path, "w") as moved_page_fd:
                     html = f"""\
 <html>
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -77,29 +77,32 @@
 try:
     import nbconvert
 except ImportError:
-    logger.warn("nbconvert not installed. Skipping notebooks.")
+    logger.warning("nbconvert not installed. Skipping notebooks.")
     exclude_patterns.append("**/*.ipynb")
 else:
     try:
         nbconvert.utils.pandoc.get_pandoc_version()
     except nbconvert.utils.pandoc.PandocMissing:
-        logger.warn("Pandoc not installed. Skipping notebooks.")
+        logger.warning("Pandoc not installed. Skipping notebooks.")
         exclude_patterns.append("**/*.ipynb")
 
 # sphinx_pattern can be '-api' to exclude the API pages,
 # the path to a file, or a Python object
 # (e.g. '10min.rst' or 'pandas.DataFrame.head')
 source_path = os.path.dirname(os.path.abspath(__file__))
 pattern = os.environ.get("SPHINX_PATTERN")
+single_doc = pattern is not None and pattern != "-api"
+include_api = pattern != "-api"
 if pattern:
     for dirname, dirs, fnames in os.walk(source_path):
+        reldir = os.path.relpath(dirname, source_path)
         for fname in fnames:
             if os.path.splitext(fname)[-1] in (".rst", ".ipynb"):
                 fname = os.path.relpath(os.path.join(dirname, fname), source_path)
 
                 if fname == "index.rst" and os.path.abspath(dirname) == source_path:
                     continue
-                elif pattern == "-api" and dirname == "reference":
+                elif pattern == "-api" and reldir.startswith("reference"):
                     exclude_patterns.append(fname)
                 elif pattern != "-api" and fname != pattern:
                     exclude_patterns.append(fname)
@@ -109,11 +112,11 @@
 with open(os.path.join(source_path, "index.rst"), "w") as f:
     f.write(
         t.render(
-            include_api=pattern is None,
-            single_doc=(pattern if pattern is not None and pattern != "-api" else None),
+            include_api=include_api,
+            single_doc=(pattern if single_doc else None),
         )
     )
-autosummary_generate = True if pattern is None else ["index"]
+autosummary_generate = True if include_api else ["index"]
 autodoc_typehints = "none"
 
 # numpydoc
@@ -315,7 +318,7 @@
         # ... and each of its public methods
         moved_api_pages.append((f"{old}.{method}", f"{new}.{method}"))
 
-if pattern is None:
+if include_api:
     html_additional_pages = {
         "generated/" + page[0]: "api_redirect.html" for page in moved_api_pages
     }
@@ -411,7 +414,7 @@
 # latex_use_modindex = True
 
 
-if pattern is None:
+if include_api:
     intersphinx_mapping = {
         "dateutil": ("https://dateutil.readthedocs.io/en/latest/", None),
         "matplotlib": ("https://matplotlib.org/", None),
