DM-25337: Add -W (warnings as errors) and -n nitpicky mode for stack-docs / package-docs build

CHANGELOG.md

@@ -12,6 +12,53 @@
   More files and directories like `.venv` and `requirements.txt` are now excluded, as well.
 - New support for embedding OpenAPI documentation in a Redoc-generated subsite. The `documenteer.ext.openapi` extension can call a user-specified function to generate and install the OpenAPI specification the Sphinx source. For user guide projects, the `[project.openapi]` table in `documenteer.toml` can be used to configure both the `documenteer.ext.openapi` and `sphinxcontrib-redoc` extensions. [sphinxcontrib-redoc](https://sphinxcontrib-redoc.readthedocs.io/en/stable/) is installed and configured by default for all Rubin user guide projects (projects that use `documenteer.conf.guide`).
 
+## 0.8.1 (2023-06-27)
+
+Fixes:
+
+- Fixed a bug in the in the `help` subcommand for the `package-docs` and `stack-docs` commands.
+
+## 0.8.0 (2023-06-23)
+
+New features:
+
+- Added a `-W` / `--warning-is-error` flag to the `package-docs build` and `stack-docs build` commands for Science Pipelines documentation builds. This flag causes Sphinx to treat warnings as errors, which is useful for CI builds.
+- Also added a `-n` / `--nitpicky` flag that enables Sphinx's nitpicky mode to flag warnings when links cannot resolve.
+
+Fixes:
+
+- Pinned `sphinx-autodoc-typehints<1.23.0` to avoid a Sphinx version conflict with `sphinx-design`. The former required Sphinx >= 7.
+
+## 0.7.5 (2023-06-07)
+
+Fixes:
+
+- Use [sphinxcontrib-jquery](https://github.com/sphinx-contrib/jquery/) to ensure jQuery is available for user guide and Pipelines documentation builds. Sphinx 6 dropped jQuery from its default theme, and the new pydata-sphinx-theme v0.12 does not include it either.
+
+## 0.7.4 (2023-05-16)
+
+Fixes:
+
+- Pinned Sphinx < 7 for the `pipelines` and `technote` extras since their themes are not currently compatible with Sphinx 7 and later.
+
+## 0.7.3 (2023-03-20)
+
+Fixes:
+
+- Add `requirements.txt` and `.venv`/`venv` to the default `exclude_patterns` for User Guides.
+
+## 0.7.2 (2023-03-01)
+
+Fixes:
+
+- Temporarily pin pydata-sphinx-theme to <0.13. The new version changed how it treats light/dark logos.
+
+## 0.7.1 (2023-02-23)
+
+Fixes:
+
+- Temporarily pinning Mermaid to 9.4.0 in the User Guide configuration to workaround a change in the Mermaid CDN.
+
 ## 0.7.0 (2022-10-20)
 
 - Documenteer provides a new Sphinx configuration profile for general Rubin user guide projects, `documenteer.conf.guide`.

src/documenteer/sphinxrunner.py

@@ -15,6 +15,7 @@ def run_sphinx(
     root_dir: Union[str, Path],
     job_count: int = 1,
     warnings_as_errors: bool = False,
+    nitpicky: bool = False,
 ) -> int:
     """Run the Sphinx build process.
 
@@ -26,6 +27,10 @@ def run_sphinx(
         configuration file.
     job_count : `int`
         Number of cores to run the Sphinx build with (``-j`` flag)
+    warnings_as_errors : `bool`
+        If ``True``, treat Sphinx warnings as errors (``-W`` flag).
+    nitpicky : `bool`
+        If ``True``, activate Sphinx's nitpicky mode (``-n`` flag).
 
     Returns
     -------
@@ -51,6 +56,8 @@ def run_sphinx(
     ]
     if warnings_as_errors:
         argv.append("-W")
+    if nitpicky:
+        argv.append("-n")
     argv.extend([src_dir, os.path.join("_build", "html")])
 
     start_dir = os.path.abspath(".")

src/documenteer/stackdocs/build.py

@@ -38,6 +38,8 @@ def build_stack_docs(
     enable_sphinx: bool = True,
     select_doxygen_packages: Optional[List[str]] = None,
     skip_doxygen_packages: Optional[List[str]] = None,
+    warning_is_error: bool = False,
+    nitpicky: bool = False,
 ) -> int:
     """Build stack Sphinx documentation (main entrypoint).
 
@@ -77,6 +79,11 @@ def build_stack_docs(
     skip_doxygen_packages
         If set, EUPS packages named in this sequence will be removed from the
         set of packages processed by Doxygen.
+    warning_is_error
+        If ``True``, warnings from Sphinx will be treated as errors.
+    nitpicky
+        If ``True``, run Sphinx in "nitpicky" mode that generates warnings
+        for more things like unresolved links.
 
     Returns
     -------
@@ -236,7 +243,11 @@ def build_stack_docs(
 
     # Trigger the Sphinx build
     if enable_sphinx:
-        return run_sphinx(root_project_dir)
+        return run_sphinx(
+            root_project_dir,
+            warnings_as_errors=warning_is_error,
+            nitpicky=nitpicky,
+        )
     else:
         return 0
 

src/documenteer/stackdocs/packagecli.py

@@ -8,6 +8,7 @@
 import os
 import shutil
 import sys
+from typing import Any
 
 import click
 
@@ -63,9 +64,7 @@ def main(ctx, root_dir, verbose):
     - ``package-docs clean``: removes documentation build products from a
       package.
     """
-    root_dir = discover_package_doc_dir(root_dir)
-
-    # Subcommands should use the click.pass_obj decorator to get this
+    # Subcommands should use the click.pass_context decorator to get this
     # ctx.obj object as the first argument.
     ctx.obj = {"root_dir": root_dir, "verbose": verbose}
 
@@ -94,14 +93,23 @@ def help(ctx, topic, **kw):
 
 
 @main.command()
+@click.option(
+    "-W", "--warning-is-error", is_flag=True, help="Treat warnings as errors."
+)
+@click.option(
+    "-n", "--nitpicky", is_flag=True, help="Activate Sphinx's nitpicky mode."
+)
 @click.pass_context
-def build(ctx):
+def build(ctx: Any, warning_is_error: bool, nitpicky: bool) -> None:
     """Build documentation as HTML.
 
     The build HTML site is located in the ``doc/_build/html`` directory
     of the package.
     """
-    return_code = run_sphinx(ctx.obj["root_dir"])
+    root_dir = discover_package_doc_dir(ctx.obj["root_dir"])
+    return_code = run_sphinx(
+        root_dir, warnings_as_errors=warning_is_error, nitpicky=nitpicky
+    )
     if return_code > 0:
         sys.exit(return_code)
 
@@ -122,10 +130,10 @@ def clean(ctx):
     """
     logger = logging.getLogger(__name__)
 
+    root_dir = discover_package_doc_dir(ctx.obj["root_dir"])
+
     dirnames = ["py-api", "_build"]
-    dirnames = [
-        os.path.join(ctx.obj["root_dir"], dirname) for dirname in dirnames
-    ]
+    dirnames = [os.path.join(root_dir, dirname) for dirname in dirnames]
     for dirname in dirnames:
         if os.path.isdir(dirname):
             shutil.rmtree(dirname)

src/documenteer/stackdocs/stackcli.py

@@ -67,9 +67,7 @@ def main(ctx, root_project_dir, verbose):
 
     For more information about stack-docs, see https://documenteer.lsst.io.
     """
-    root_project_dir = discover_conf_py_directory(root_project_dir)
-
-    # Subcommands should use the click.pass_obj decorator to get this
+    # Subcommands should use the click.pass_context decorator to get this
     # ctx.obj object as the first argument.
     ctx.obj = {"root_project_dir": root_project_dir, "verbose": verbose}
 
@@ -162,6 +160,12 @@ def help(ctx, topic, **kw):
     multiple=True,
     help=("Skip running Doxygen on these packages."),
 )
+@click.option(
+    "-W", "--warning-is-error", is_flag=True, help="Treat warnings as errors."
+)
+@click.option(
+    "-n", "--nitpicky", is_flag=True, help="Activate Sphinx's nitpicky mode."
+)
 @click.pass_context
 def build(
     ctx,
@@ -174,6 +178,8 @@ def build(
     doxygen_conf_defaults_path,
     dox,
     skip_dox,
+    warning_is_error,
+    nitpicky,
 ):
     """Build documentation as HTML.
 
@@ -197,13 +203,15 @@ def build(
     To peek inside the build process, see the ``documenteer.stackdocs.build``
     APIs.
     """
+    root_project_dir = discover_conf_py_directory(ctx.obj["root_project_dir"])
+
     if doxygen_conf_defaults_path is not None:
         _doxygen_conf_defaults_path = Path(doxygen_conf_defaults_path)
     else:
         _doxygen_conf_defaults_path = None
 
     return_code = build_stack_docs(
-        ctx.obj["root_project_dir"],
+        root_project_dir,
         skipped_names=skip,
         prefer_doxygen_conf_in=use_doxygen_conf_in,
         doxygen_conf_defaults_path=_doxygen_conf_defaults_path,
@@ -213,6 +221,8 @@ def build(
         enable_sphinx=enable_sphinx,
         select_doxygen_packages=dox,
         skip_doxygen_packages=skip_dox,
+        warning_is_error=warning_is_error,
+        nitpicky=nitpicky,
     )
     if return_code > 0:
         sys.exit(return_code)
@@ -237,10 +247,10 @@ def clean(ctx):
     """
     logger = logging.getLogger(__name__)
 
+    root_project_dir = discover_conf_py_directory(ctx.obj["root_project_dir"])
     dirnames = ["py-api", "_build", "modules", "packages", "_doxygen"]
     dirnames = [
-        os.path.join(ctx.obj["root_project_dir"], dirname)
-        for dirname in dirnames
+        os.path.join(root_project_dir, dirname) for dirname in dirnames
     ]
     for dirname in dirnames:
         if os.path.isdir(dirname):
@@ -302,9 +312,8 @@ def listcc(
 
         stack-docs listcc -t class -t function -p lsst::afw::table
     """
-    tag_path = os.path.join(
-        ctx.obj["root_project_dir"], "_doxygen", "doxygen.tag"
-    )
+    root_project_dir = discover_conf_py_directory(ctx.obj["root_project_dir"])
+    tag_path = os.path.join(root_project_dir, "_doxygen", "doxygen.tag")
 
     if pattern:
         p = re.compile(pattern)