test_sphinx_write_safety.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_docs/test_sphinx_write_safety.py
 
"""
Purpose
-------
OI-518 regression coverage — ``oct docs --sphinx`` must not silently
overwrite user-authored files in ``docs/``. The pipeline may only
regenerate files it previously wrote (identified by an ``Auto-generated
by oct docs --sphinx`` marker on their first line).
 
Protected files:
    - docs/README.md            (copied from root, now marker-guarded)
    - docs/index.rst            (regenerated each build)
    - docs/dependencies.rst     (regenerated when graph has edges)
    - docs/_api/modules.rst     (regenerated by sphinx-apidoc wrapper)
 
Responsibilities
----------------
- Verify ``_is_auto_generated`` marker detection for absent and existing
  files.
- Verify user-authored files survive a Sphinx documentation build.
- Verify generated (marker-present) files are refreshed from their source.
 
Diagnostics
-----------
Domain: DOCS-TESTS
Levels:
    L2 — test lifecycle
    L3 — assertion details
    L4 — deep tracing
 
Contracts
---------
- ``_is_auto_generated(path, marker)`` returns True when file is absent
  or first line carries the marker; False otherwise.
- A pre-existing user-authored ``docs/README.md`` survives a Sphinx run.
- A generated ``docs/README.md`` (marker present) is refreshed from root.
"""
 
from __future__ import annotations
 
from pathlib import Path
 
import pytest
 
from oct.docs import oct_docs
from oct.docs.oct_docs import (
    _AUTO_MARKER_MD,
    _AUTO_MARKER_RST,
    _is_auto_generated,
)
 
 
def test_is_auto_generated_absent(tmp_path: Path) -> None:
    """Non-existent paths are safe to write — treated as auto-generated."""
    assert _is_auto_generated(tmp_path / "missing.rst", _AUTO_MARKER_RST)
 
 
def test_is_auto_generated_marker_matches(tmp_path: Path) -> None:
    """A file whose first line carries the marker is auto-generated."""
    path = tmp_path / "index.rst"
    path.write_text(
        f"{_AUTO_MARKER_RST}. Edits will be overwritten.\n\nBody\n",
        encoding="utf-8",
    )
    assert _is_auto_generated(path, _AUTO_MARKER_RST) is True
 
 
def test_is_auto_generated_user_authored(tmp_path: Path) -> None:
    """A file without the marker is treated as user-authored."""
    path = tmp_path / "README.md"
    path.write_text("# My Hand-Written Docs\n\nHello.\n", encoding="utf-8")
    assert _is_auto_generated(path, _AUTO_MARKER_MD) is False
 
 
def test_run_docs_sphinx_preserves_user_readme(
    tmp_path: Path, monkeypatch,
) -> None:
    """OI-518: ``run_docs_sphinx`` must not clobber a user's docs/README.md."""
    root = tmp_path / "proj"
    docs = root / "docs"
    docs.mkdir(parents=True)
 
    # User has hand-authored docs/README.md *and* a root README.md that
    # differs. The pipeline used to unconditionally copy the root file
    # on top of the user's docs/ file.
    user_readme = docs / "README.md"
    user_readme.write_text("# Hand-written\n", encoding="utf-8")
    (root / "README.md").write_text("# Root\n", encoding="utf-8")
 
    # Short-circuit the expensive parts: dependency check, setup, api/deps
    # generation, index write, and the subprocess invocation.
    monkeypatch.setattr(oct_docs, "_check_sphinx_deps", lambda: [])
    monkeypatch.setattr(oct_docs, "setup_sphinx", lambda r: r / "docs")
    monkeypatch.setattr(oct_docs, "_generate_api_rst",
                        lambda r, d, c: False)
    monkeypatch.setattr(oct_docs, "_generate_deps_rst", lambda r, d: False)
    monkeypatch.setattr(oct_docs, "_write_index_rst",
                        lambda *a, **kw: None)
    monkeypatch.setattr(oct_docs, "run_sphinx_build", lambda d, c: 0)
 
    rc = oct_docs.run_docs_sphinx(root)
    assert rc == 0
    # User-authored content must survive.
    assert user_readme.read_text(encoding="utf-8") == "# Hand-written\n"
 
 
def test_run_docs_sphinx_refreshes_generated_readme(
    tmp_path: Path, monkeypatch,
) -> None:
    """OI-518: a marker-carrying docs/README.md is refreshed from root."""
    root = tmp_path / "proj"
    docs = root / "docs"
    docs.mkdir(parents=True)
 
    # A previously generated docs/README.md carries the marker. The
    # pipeline should overwrite it with the current root README.
    (docs / "README.md").write_text(
        f"{_AUTO_MARKER_MD}\n\n# Stale Root\n", encoding="utf-8",
    )
    (root / "README.md").write_text("# Fresh Root\n", encoding="utf-8")
 
    monkeypatch.setattr(oct_docs, "_check_sphinx_deps", lambda: [])
    monkeypatch.setattr(oct_docs, "setup_sphinx", lambda r: r / "docs")
    monkeypatch.setattr(oct_docs, "_generate_api_rst",
                        lambda r, d, c: False)
    monkeypatch.setattr(oct_docs, "_generate_deps_rst", lambda r, d: False)
    monkeypatch.setattr(oct_docs, "_write_index_rst",
                        lambda *a, **kw: None)
    monkeypatch.setattr(oct_docs, "run_sphinx_build", lambda d, c: 0)
 
    rc = oct_docs.run_docs_sphinx(root)
    assert rc == 0
    refreshed = (docs / "README.md").read_text(encoding="utf-8")
    assert "# Fresh Root" in refreshed
    assert refreshed.startswith(_AUTO_MARKER_MD)