test_docs_clean.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_docs/test_docs_clean.py
 
"""
Purpose
-------
Validate the ``oct docs --clean`` pipeline (run_docs_clean).
 
Responsibilities
----------------
- Confirm generated directories (html, doctrees, _api, doxygen_output) are removed.
- Confirm generated files (index.rst, dependencies.rst) are removed.
- Confirm preserved files (_sphinx/conf.py, _static/, user-authored .md) survive.
- Confirm dry-run mode does not delete anything.
- Confirm running on a project with no docs/ is a no-op.
 
Diagnostics
-----------
Domain: DOCS-TESTS
L2: test lifecycle
L3: assertion details
L4: deep tracing
 
Contracts
---------
Inputs:  tmp_path pytest fixture
Outputs: pass/fail assertions
"""
 
from pathlib import Path
import pytest
from oct.docs.oct_docs import run_docs_clean
 
 
@pytest.fixture
def docs_tree(tmp_path: Path) -> Path:
    """Create a realistic docs/ directory with generated and user-authored files."""
    root = tmp_path / "project"
    docs = root / "docs"
 
    # Generated directories
    (docs / "html").mkdir(parents=True)
    (docs / "html" / "index.html").write_text("<html/>", encoding="utf-8")
    (docs / "doctrees").mkdir()
    (docs / "doctrees" / "index.doctree").write_bytes(b"\x00")
    (docs / "_api").mkdir()
    (docs / "_api" / "modules.rst").write_text("API\n", encoding="utf-8")
    (docs / "doxygen_output" / "html").mkdir(parents=True)
    (docs / "doxygen_output" / "html" / "index.html").write_text("<html/>", encoding="utf-8")
 
    # Generated files
    (docs / "index.rst").write_text(".. toctree::\n", encoding="utf-8")
    (docs / "dependencies.rst").write_text("deps\n", encoding="utf-8")
 
    # Preserved: user-authored content
    (docs / "ARCHITECTURE.md").write_text("# Arch\n", encoding="utf-8")
    (docs / "ROADMAP.md").write_text("# Roadmap\n", encoding="utf-8")
 
    # Preserved: Sphinx config
    (docs / "_sphinx").mkdir()
    (docs / "_sphinx" / "conf.py").write_text("# conf\n", encoding="utf-8")
 
    # Preserved: static assets
    (docs / "_static").mkdir()
    (docs / "_static" / "custom.css").write_text("body {}\n", encoding="utf-8")
 
    # Preserved: Doxyfile
    (docs / "doxygen_work_dir").mkdir()
    (docs / "doxygen_work_dir" / "Doxyfile").write_text("INPUT =\n", encoding="utf-8")
 
    return root
 
 
def test_clean_removes_generated_dirs(docs_tree: Path):
    """Generated directories (html, doctrees, _api, doxygen_output) are removed."""
    rc = run_docs_clean(docs_tree)
    assert rc == 0
    docs = docs_tree / "docs"
    assert not (docs / "html").exists()
    assert not (docs / "doctrees").exists()
    assert not (docs / "_api").exists()
    assert not (docs / "doxygen_output").exists()
 
 
def test_clean_removes_generated_files(docs_tree: Path):
    """Generated files (index.rst, dependencies.rst) are removed."""
    rc = run_docs_clean(docs_tree)
    assert rc == 0
    docs = docs_tree / "docs"
    assert not (docs / "index.rst").exists()
    assert not (docs / "dependencies.rst").exists()
 
 
def test_clean_preserves_user_content(docs_tree: Path):
    """User-authored markdown files survive clean."""
    run_docs_clean(docs_tree)
    docs = docs_tree / "docs"
    assert (docs / "ARCHITECTURE.md").exists()
    assert (docs / "ROADMAP.md").exists()
 
 
def test_clean_preserves_sphinx_config(docs_tree: Path):
    """Sphinx config directory (_sphinx/) survives clean."""
    run_docs_clean(docs_tree)
    assert (docs_tree / "docs" / "_sphinx" / "conf.py").exists()
 
 
def test_clean_preserves_static(docs_tree: Path):
    """Static assets directory (_static/) survives clean."""
    run_docs_clean(docs_tree)
    assert (docs_tree / "docs" / "_static" / "custom.css").exists()
 
 
def test_clean_preserves_doxyfile(docs_tree: Path):
    """Doxyfile in doxygen_work_dir/ survives clean."""
    run_docs_clean(docs_tree)
    assert (docs_tree / "docs" / "doxygen_work_dir" / "Doxyfile").exists()
 
 
def test_dry_run_preserves_everything(docs_tree: Path):
    """Dry-run mode reports but does not delete anything."""
    rc = run_docs_clean(docs_tree, dry_run=True)
    assert rc == 0
    docs = docs_tree / "docs"
    # Everything should still exist
    assert (docs / "html").exists()
    assert (docs / "doctrees").exists()
    assert (docs / "_api").exists()
    assert (docs / "doxygen_output").exists()
    assert (docs / "index.rst").exists()
    assert (docs / "dependencies.rst").exists()
 
 
def test_no_docs_dir(tmp_path: Path):
    """No docs/ directory — clean is a no-op."""
    root = tmp_path / "empty-project"
    root.mkdir()
    rc = run_docs_clean(root)
    assert rc == 0
 
 
def test_already_clean(docs_tree: Path):
    """Running clean twice is idempotent."""
    run_docs_clean(docs_tree)
    rc = run_docs_clean(docs_tree)
    assert rc == 0