lctio-docs

# LCTIO Docs Use this skill for changes under `docs/`, Sphinx configuration updates, and documentation build validation. ## Workflow 1. Refresh repository state before editing. 2. If `./.venv/` exists, use `./.venv/bin/python` and tools from that environment for docs installs and builds. 3. Inspect `docs/source/conf.py`, `docs/Makefile`, and any new docs files you will touch. 4. Check `pyproject.toml` for the current packaging and dependency layout before assuming docs dependencies exist. 5. For `autodoc` and related extensions, prefer installing the project in editable mode with the local virtual environment so imports resolve from `src/`. 6. Manage docs-only dependencies with a docs extra in `pyproject.toml`. 7. Run a clean docs build after config or content changes and treat warnings as important review items. ## Core Commands - `./.venv/bin/python -m pip install -e .` - `./.venv/bin/python -m pip install -e .[docs]` - `PATH="$PWD/.venv/bin:$PATH" make -C docs html` - `./.venv/bin/python -m sphinx -b html docs/source docs/build/html` - `./.venv/bin/python -m sphinx -W -b html docs/source docs/build/html` - `make -C docs clean` - `PATH="$PWD/.venv/bin:$PATH" make -C docs clean` - `./.venv/bin/python -m sphinx -b linkcheck docs/source docs/build/linkcheck` - `./.venv/bin/python -m sphinx -b doctest docs/source docs/build/doctest` ## Autodoc Notes - If Sphinx cannot import `lctio`, first verify the editable install rather than immediately patching `sys.path`. - If runtime-only dependencies break docs imports, prefer `autodoc_mock_imports` for optional packages instead of hiding real import failures from this package. ## What To Confirm With The User - Which Sphinx extensions and themes are approved for the project. - Whether warnings should fail validation by default with `-W` for the current change. - Whether a failure is likely caused by local environment constraints, optional dependencies, or network access. ## Expectations - Keep generated docs output under `docs/build/` treated as generated unless the user asks to commit it. - Prefer validating only the docs targets affected by the change, then run a stricter warning-failing build when the change touches configuration or shared content. - Investigate warnings and validation failures enough to identify whether they are actionable code or docs issues versus environment-sensitive failures. - For `linkcheck`, external links may fail because of transient network or remote-site behavior; report that clearly instead of treating every failure as a docs defect. - For doctest or example-code validation, expect some failures to depend on local environment state. Do not spend extended effort on repeated or ambiguous failures before consulting the user.