test: add tests

.github/workflows/test.yaml

@@ -10,49 +10,58 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-    linting:
-        runs-on: ubuntu-latest
+  linting:
+    runs-on: ubuntu-latest
 
-        steps:
-        - uses: actions/checkout@v4
+    steps:
+      - uses: actions/checkout@v4
 
-        - name: Setup Python
-          uses: actions/setup-python@v5
-          with:
-              python-version: "3.10"
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
 
-        - name: Install Dependencies
-          run: |
-            python -m pip install --upgrade pip
-            pip install .[lint]
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[lint]
 
-        - name: Run Black
-          run: black --check .
+      - name: Run Black
+        run: black --check .
 
-        - name: Run isort
-          run: isort --check-only .
+      - name: Run isort
+        run: isort --check-only .
 
-        - name: Run flake8
-          run: flake8 .
+      - name: Run flake8
+        run: flake8 .
 
-        - name: Run mdformat
-          run: mdformat . --check
+      - name: Run mdformat
+        run: mdformat . --check
 
-    type-check:
-        runs-on: ubuntu-latest
+  type-check:
+    runs-on: ubuntu-latest
 
-        steps:
-        - uses: actions/checkout@v4
+    steps:
+    - uses: actions/checkout@v4
 
-        - name: Setup Python
-          uses: actions/setup-python@v5
-          with:
-              python-version: "3.10"
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
 
-        - name: Install Dependencies
-          run: |
-            python -m pip install --upgrade pip
-            pip install .[lint]
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[lint,test]
 
-        - name: Run MyPy
-          run: mypy .
+    - name: Run MyPy
+      run: mypy .
+
+  tests:
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[test]
+
+    - name: Run Pytest
+      run: pytest  

setup.py

@@ -2,6 +2,10 @@
 from setuptools import find_packages, setup
 
 extras_require = {
+    "test": [
+        "pytest>=8.3.2,<9",
+        "pytest-mock>=3.14.0,<4",
+    ],
     "lint": [
         "black>=24.4.2,<25",  # Auto-formatter and linter
         "mypy>=1.10.0,<2",  # Static type analyzer
@@ -31,7 +35,12 @@
 }
 
 # NOTE: `pip install -e .[dev]` to install package
-extras_require["dev"] = extras_require["lint"] + extras_require["release"] + extras_require["dev"]
+extras_require["dev"] = (
+    extras_require["lint"]
+    + extras_require["release"]
+    + extras_require["test"]
+    + extras_require["dev"]
+)
 
 with open("./README.md") as readme:
     long_description = readme.read()

sphinx_ape/_cli.py

@@ -18,8 +18,7 @@ def cli():
 def build_mode_option():
     return click.option(
         "--mode",
-        callback=lambda c, p, v: BuildMode.init(v),
-        type=BuildMode,
+        callback=lambda c, p, v: BuildMode(v),
         default=BuildMode.LATEST,
     )
 

sphinx_ape/build.py

@@ -34,6 +34,10 @@ def init(cls, identifier: Optional[Union[str, "BuildMode"]] = None) -> "BuildMod
             return BuildMode(identifier)
 
         elif isinstance(identifier, str):
+            if "." in identifier:
+                # Click being weird, value like "buildmode.release".
+                identifier = identifier.split(".")[-1].upper()
+
             # GitHub event name.
             return BuildMode.RELEASE if identifier.lower() == "release" else BuildMode.LATEST
 
@@ -104,15 +108,15 @@ def build(self):
 
         elif self.mode is BuildMode.RELEASE:
             # TRIGGER: Release on GitHub
-            self.build_release()
+            self._build_release()
 
         else:
             # Unknown 'mode'.
             raise ApeDocsBuildError(f"Unsupported build-mode: {self.mode}")
 
         self._setup_redirect()
 
-    def build_release(self):
+    def _build_release(self):
         if not (tag := git("describe", "--tag")):
             raise ApeDocsBuildError("Unable to find release tag.")
 
@@ -127,6 +131,9 @@ def build_release(self):
             build_dir = self.build_path / tag
             self._sphinx_build(build_dir)
 
+            if not build_dir.is_dir():
+                return
+
             # Clean-up unnecessary extra 'fonts/' directories to save space.
             # There should still be one in 'latest/'
             for font_dirs in build_dir.glob("**/fonts"):

tests/conftest.py

@@ -0,0 +1,10 @@
+import tempfile
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def temp_path():
+    with tempfile.TemporaryDirectory() as temp:
+        yield Path(temp).resolve()

tests/test_build.py

@@ -0,0 +1,72 @@
+from pathlib import Path
+
+import pytest
+
+from sphinx_ape.build import BuildMode, DocumentationBuilder
+
+
+class TestBuildMode:
+    @pytest.mark.parametrize("val", ("latest", 0, "pull_request", "buildmode.latest"))
+    def test_init_latest(self, val):
+        mode = BuildMode.init("val")
+        assert mode is BuildMode.LATEST
+
+    @pytest.mark.parametrize("val", ("release", 1, "buildmode.release"))
+    def test_init_release(self, val):
+        mode = BuildMode.init(val)
+        assert mode is BuildMode.RELEASE
+
+
+class TestDocumentationBuilder:
+    @pytest.fixture(autouse=True)
+    def mock_sphinx(self, mocker):
+        def run_mock_sphinx(path, *args, **kwargs):
+            path.mkdir(parents=True)
+            buildfile = path / "build.txt"
+            buildfile.touch()
+
+        mock = mocker.patch("sphinx_ape.build.sphinx_build")
+        mock.side_effect = run_mock_sphinx
+        return mock
+
+    @pytest.fixture(autouse=True)
+    def mock_git(self, mocker):
+        return mocker.patch("sphinx_ape.build.git")
+
+    def test_build_latest(self, mock_sphinx, temp_path):
+        builder = DocumentationBuilder(mode=BuildMode.LATEST, base_path=temp_path)
+        builder.build()
+        call_path = mock_sphinx.call_args[0][0]
+        self.assert_build_path(call_path, "latest")
+
+    def test_build_release(self, mock_sphinx, mock_git, temp_path):
+        tag = "v1.0.0"
+        mock_git.return_value = tag
+        builder = DocumentationBuilder(mode=BuildMode.RELEASE, base_path=temp_path)
+        builder.build()
+        call_path = mock_sphinx.call_args[0][0]
+        self.assert_build_path(call_path, tag)
+        # Latest and Stable should also have been created!
+        self.assert_build_path(call_path.parent / "latest", "latest")
+        self.assert_build_path(call_path.parent / "stable", "stable")
+
+    @pytest.mark.parametrize("sub_tag", ("alpha", "beta"))
+    def test_build_alpha_release(self, sub_tag, mock_sphinx, mock_git, temp_path):
+        """
+        We don't build version releases when using alpha or beta, but we
+        still update "stable" and "latest".
+        """
+        tag = f"v1.0.0{sub_tag}"
+        mock_git.return_value = tag
+        builder = DocumentationBuilder(mode=BuildMode.RELEASE, base_path=temp_path)
+        builder.build()
+        call_path = mock_sphinx.call_args[0][0]
+        self.assert_build_path(call_path, "stable")
+        # Latest should also have been created!
+        self.assert_build_path(call_path.parent / "latest", "latest")
+
+    def assert_build_path(self, path: Path, expected: str):
+        assert path.name == expected  # Tag, latest, or stable
+        assert path.parent.name == "sphinx-ape"  # Project name, happens to be this lib
+        assert path.parent.parent.name == "_build"  # Sphinx-ism
+        assert path.parent.parent.parent.name == "docs"  # Sphinx-ism

tests/test_utils.py

@@ -0,0 +1,27 @@
+from sphinx_ape.utils import extract_package_name
+
+
+def test_extract_package_name_setup_py(temp_path):
+    setup_py = temp_path / "setup.py"
+    name = "ape-myplugin"
+    content = f"""
+#!/usr/bin/env python
+
+from setuptools import find_packages, setup
+extras_require = {{
+    "test": [  # `test` GitHub Action jobs uses this
+        "pytest>=6.0",  # Core testing package
+    ],
+}}
+setup(
+    name="{name}",
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Programming Language :: Python :: 3.12",
+    ],
+)
+"""
+    setup_py.write_text(content)
+
+    actual = extract_package_name(temp_path)
+    assert actual == name