Merge pull request #168 from lsst-sqre/tickets/DM-25337-help

DM-25337: Fix stack-docs/package-docs help command (0.8.1 release)

CHANGELOG.md

@@ -1,10 +1,17 @@
 # Change Log
 
+## 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-07-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:
 

src/documenteer/stackdocs/packagecli.py

@@ -64,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}
 
@@ -108,8 +106,9 @@ def build(ctx: Any, warning_is_error: bool, nitpicky: bool) -> None:
     The build HTML site is located in the ``doc/_build/html`` directory
     of the package.
     """
+    root_dir = discover_package_doc_dir(ctx["root_dir"])
     return_code = run_sphinx(
-        ctx.obj["root_dir"],
+        root_dir,
         warnings_as_errors=warning_is_error,
         nitpicky=nitpicky,
     )
@@ -133,10 +132,10 @@ def clean(ctx):
     """
     logger = logging.getLogger(__name__)
 
+    root_dir = discover_package_doc_dir(ctx["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}
 
@@ -205,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,
@@ -247,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):
@@ -312,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)