From 46d8adb0bcd3fc24f90db194c636a7bcf85a437c Mon Sep 17 00:00:00 2001 From: Richard Shadrach Date: Thu, 31 Dec 2020 12:14:35 -0500 Subject: [PATCH 1/2] DOC/CI: Fix building docs with --no-api --- doc/make.py | 18 ++++++++++++------ doc/source/conf.py | 19 +++++++++++-------- 2 files changed, 23 insertions(+), 14 deletions(-) diff --git a/doc/make.py b/doc/make.py index 40ce9ea3bbcd2..6c4d6d094feb1 100755 --- 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,17 @@ 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 +209,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"""\ diff --git a/doc/source/conf.py b/doc/source/conf.py index 951a6d4043786..3508dc2edd84c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -72,13 +72,13 @@ 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, @@ -86,15 +86,18 @@ # (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) @@ -104,11 +107,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 @@ -310,7 +313,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 } @@ -406,7 +409,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), From 488af98b298d0bb0e4c6b6512f05b440b7b5b7c1 Mon Sep 17 00:00:00 2001 From: Richard Shadrach Date: Thu, 31 Dec 2020 17:46:06 +0000 Subject: [PATCH 2/2] Fixes from pre-commit [automated commit] --- doc/make.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/doc/make.py b/doc/make.py index 6c4d6d094feb1..d90cd2428360d 100755 --- a/doc/make.py +++ b/doc/make.py @@ -192,12 +192,9 @@ def _add_redirects(self): 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 - ) + if not self.include_api and ( + os.path.join(html_path, "reference") in path + or os.path.join(html_path, "generated") in path ): continue