chore: ensure not empty TOC

sphinx_ape/_cli.py

@@ -6,7 +6,7 @@
 
 from sphinx_ape._utils import get_package_name
 from sphinx_ape.build import BuildMode, DocumentationBuilder
-from sphinx_ape.exceptions import ApeDocsBuildError, ApeDocsPublishError, ApeDocsTestError
+from sphinx_ape.exceptions import BuildError, PublishError, TestError
 from sphinx_ape.testing import DocumentationTester
 
 
@@ -64,7 +64,7 @@ def build(base_path, mode, package_name):
     click.echo(f"Building '{package_name}' '{mode.name}'.")
     try:
         builder.build()
-    except ApeDocsBuildError as err:
+    except BuildError as err:
         click.echo(f"ERROR: {err}", err=True)
         sys.exit(1)
 
@@ -124,7 +124,7 @@ def test(base_path):
     tester = _create_tester(base_path=base_path)
     try:
         tester.test()
-    except ApeDocsTestError as err:
+    except TestError as err:
         click.echo(f"ERROR: {err}", err=True)
         sys.exit(1)
 
@@ -149,7 +149,7 @@ def publish(base_path, mode, repo, skip_push):
     builder = _create_builder(mode=mode, base_path=base_path)
     try:
         builder.publish(repository=repo, push=not skip_push)
-    except ApeDocsPublishError as err:
+    except PublishError as err:
         click.echo(f"ERROR: {err}", err=True)
         sys.exit(1)
 

sphinx_ape/_utils.py

@@ -7,7 +7,7 @@
 
 import tomli
 
-from sphinx_ape.exceptions import ApeDocsBuildError
+from sphinx_ape.exceptions import BuildError
 
 # Avoid needing to have common Ape packages re-configure this.
 PACKAGE_ALIASES = {
@@ -32,7 +32,7 @@ def sphinx_build(dst_path: Path, source_dir: Union[Path, str]) -> Path:
     try:
         subprocess.check_call(["sphinx-build", str(source_dir), str(path)])
     except subprocess.SubprocessError as err:
-        raise ApeDocsBuildError(f"Command 'sphinx-build docs {path}' failed.") from err
+        raise BuildError(f"Command 'sphinx-build docs {path}' failed.") from err
 
     return path
 
@@ -50,7 +50,7 @@ def extract_source_url(directory: Optional[Path] = None) -> str:
     if (directory / "setup.py").is_file():
         url = _extract_github_url_from_setup_py(directory / "setup.py")
     if url is None:
-        raise ApeDocsBuildError("No package source URL found.")
+        raise BuildError("No package source URL found.")
 
     return url
 
@@ -129,7 +129,7 @@ def extract_package_name(directory: Optional[Path] = None) -> str:
         pkg_name = _extract_name_from_pyproject_toml(directory / "pyproject.toml")
     if pkg_name is None:
         path = f"{directory}".replace(f"{Path.home()}", "$HOME")
-        raise ApeDocsBuildError(f"No package name found at '{path}'.")
+        raise BuildError(f"No package name found at '{path}'.")
 
     return PACKAGE_ALIASES.get(pkg_name, pkg_name)
 

sphinx_ape/build.py

@@ -6,7 +6,7 @@
 
 from sphinx_ape._base import Documentation
 from sphinx_ape._utils import extract_source_url, git, replace_tree, sphinx_build
-from sphinx_ape.exceptions import ApeDocsBuildError, ApeDocsPublishError
+from sphinx_ape.exceptions import BuildError, PublishError
 from sphinx_ape.types import TOCTreeSpec
 
 REDIRECT_HTML = """
@@ -102,7 +102,7 @@ def build(self):
 
         else:
             # Unknown 'mode'.
-            raise ApeDocsBuildError(f"Unsupported build-mode: {self.mode}")
+            raise BuildError(f"Unsupported build-mode: {self.mode}")
 
         self._setup_redirect()
 
@@ -129,7 +129,7 @@ def publish(self, repository: Optional[str] = None, push: bool = True):
         try:
             self._publish(repository=repository, push=push)
         except Exception as err:
-            raise ApeDocsPublishError(str(err)) from err
+            raise PublishError(str(err)) from err
 
     def _publish(self, repository: Optional[str] = None, push: bool = True):
         if repository:
@@ -184,7 +184,7 @@ def _publish(self, repository: Optional[str] = None, push: bool = True):
 
     def _build_release(self):
         if not (tag := git("describe", "--tag")):
-            raise ApeDocsBuildError("Unable to find release tag.")
+            raise BuildError("Unable to find release tag.")
 
         if "beta" in tag or "alpha" in tag:
             # Avoid creating release directory for beta

sphinx_ape/exceptions.py

@@ -4,19 +4,21 @@ class SphinxApeException(Exception):
     """
 
 
-class ApeDocsBuildError(SphinxApeException):
+class BuildError(SphinxApeException):
     """
     Building the docs failed.
     """
 
 
-class ApeDocsTestError(SphinxApeException):
+class TestError(SphinxApeException):
     """
     Running doc-tests failed.
     """
 
+    __test__ = False
 
-class ApeDocsPublishError(SphinxApeException):
+
+class PublishError(SphinxApeException):
     """
     Publishing the docs failed.
     """

sphinx_ape/sphinx_ext/directives.py

@@ -5,6 +5,7 @@
 from sphinx.util.docutils import SphinxDirective
 
 from sphinx_ape.build import DocumentationBuilder
+from sphinx_ape.exceptions import BuildError
 from sphinx_ape.types import TOCTreeSpec
 
 
@@ -68,6 +69,7 @@ def run(self):
         userguides = self._get_userguides()
         cli_docs = self._get_cli_references()
         methoddocs = self._get_methoddocs()
+
         if plugin_prefix := self.plugin_prefix:
             plugin_methoddocs = [d for d in methoddocs if Path(d).stem.startswith(plugin_prefix)]
         else:
@@ -99,6 +101,10 @@ def run(self):
         if toc_tree_rst:
             restructured_text = f"{restructured_text}\n\n{toc_tree_rst}"
 
+        # Ensure TOC is not empty (no docs?).
+        if not sections or not any(len(x) for x in sections.values()):
+            raise BuildError("Empty TOC.")
+
         return self.parse_text_to_nodes(restructured_text)
 
     def _get_userguides(self) -> list[str]:

sphinx_ape/testing.py

@@ -2,7 +2,7 @@
 from pathlib import Path
 
 from sphinx_ape._base import Documentation
-from sphinx_ape.exceptions import ApeDocsBuildError, ApeDocsTestError
+from sphinx_ape.exceptions import BuildError, TestError
 
 
 class DocumentationTester(Documentation):
@@ -38,12 +38,12 @@ def test(self):
             return
 
         # Failures.
-        raise ApeDocsTestError(output)
+        raise TestError(output)
 
     def _run_tests(self):
         try:
             subprocess.run(
                 ["sphinx-build", "-b", "doctest", "docs", str(self.doctest_folder)], check=True
             )
         except subprocess.CalledProcessError as err:
-            raise ApeDocsBuildError(str(err)) from err
+            raise BuildError(str(err)) from err