Functions
None	test_is_auto_generated_absent (Path tmp_path)
None	test_is_auto_generated_marker_matches (Path tmp_path)
None	test_is_auto_generated_user_authored (Path tmp_path)
None	test_run_docs_sphinx_preserves_user_readme (Path tmp_path, monkeypatch)
None	test_run_docs_sphinx_refreshes_generated_readme (Path tmp_path, monkeypatch)

Detailed Description

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.

Function Documentation

◆ test_is_auto_generated_absent()

None tests_docs.test_sphinx_write_safety.test_is_auto_generated_absent ( Path tmp_path )

Non-existent paths are safe to write — treated as auto-generated.

Definition at line 56 of file test_sphinx_write_safety.py.

◆ test_is_auto_generated_marker_matches()

None tests_docs.test_sphinx_write_safety.test_is_auto_generated_marker_matches ( Path tmp_path )

A file whose first line carries the marker is auto-generated.

Definition at line 61 of file test_sphinx_write_safety.py.

◆ test_is_auto_generated_user_authored()

None tests_docs.test_sphinx_write_safety.test_is_auto_generated_user_authored ( Path tmp_path )

A file without the marker is treated as user-authored.

Definition at line 71 of file test_sphinx_write_safety.py.

◆ test_run_docs_sphinx_preserves_user_readme()

None tests_docs.test_sphinx_write_safety.test_run_docs_sphinx_preserves_user_readme	(	Path	tmp_path,
			monkeypatch )

OI-518: ``run_docs_sphinx`` must not clobber a user's docs/README.md.

Definition at line 78 of file test_sphinx_write_safety.py.

◆ test_run_docs_sphinx_refreshes_generated_readme()

None tests_docs.test_sphinx_write_safety.test_run_docs_sphinx_refreshes_generated_readme	(	Path	tmp_path,
			monkeypatch )

OI-518: a marker-carrying docs/README.md is refreshed from root.

Definition at line 110 of file test_sphinx_write_safety.py.