Skip to content

Make the Read the Docs build work - #28

Merged
picaultj merged 1 commit into
mainfrom
feat/readthedocs-config
Aug 31, 2026
Merged

Make the Read the Docs build work#28
picaultj merged 1 commit into
mainfrom
feat/readthedocs-config

Conversation

@picaultj

Copy link
Copy Markdown
Owner

The committed .readthedocs.yaml was still the unmodified template: it pointed sphinx.configuration at docs/conf.py, which did not exist, so every build failed. Fill it in and add the Sphinx setup it referenced.

  • docs/conf.py: Sphinx + MyST + Furo, version read from pyproject.toml so it tracks the release bumped by release.yml.
  • docs/index.md: landing page including the README, with a toctree to ARCHITECTURE.
  • docs/requirements.txt: doc toolchain only. The docs are prose, so ConfLens itself is never imported at build time and the heavy LLM / NiceGUI dependencies stay out of the build.
  • sphinxcontrib-mermaid + myst_fence_as_directive, so the ```mermaid fences in ARCHITECTURE.md and the README render as diagrams instead of failing syntax highlighting.
  • formats: [] — PDF/epub need a headless browser to rasterize mermaid, which the Read the Docs builders do not have.
  • README: point the LICENSE and .env.example links at the repository. Being relative, they resolved outside the docs tree and 404'd in the rendered site; the absolute URLs work in both places.

Known remaining warning: README references docs/overview.png, which has never been committed. That image is already broken on GitHub.

The committed .readthedocs.yaml was still the unmodified template: it
pointed `sphinx.configuration` at docs/conf.py, which did not exist, so
every build failed. Fill it in and add the Sphinx setup it referenced.

- docs/conf.py: Sphinx + MyST + Furo, version read from pyproject.toml so
  it tracks the release bumped by release.yml.
- docs/index.md: landing page including the README, with a toctree to
  ARCHITECTURE.
- docs/requirements.txt: doc toolchain only. The docs are prose, so
  ConfLens itself is never imported at build time and the heavy LLM /
  NiceGUI dependencies stay out of the build.
- sphinxcontrib-mermaid + myst_fence_as_directive, so the ```mermaid
  fences in ARCHITECTURE.md and the README render as diagrams instead of
  failing syntax highlighting.
- formats: [] — PDF/epub need a headless browser to rasterize mermaid,
  which the Read the Docs builders do not have.
- README: point the LICENSE and .env.example links at the repository.
  Being relative, they resolved outside the docs tree and 404'd in the
  rendered site; the absolute URLs work in both places.

Known remaining warning: README references docs/overview.png, which has
never been committed. That image is already broken on GitHub.
@picaultj
picaultj merged commit 90441f3 into main Aug 31, 2026
4 checks passed
@picaultj
picaultj deleted the feat/readthedocs-config branch August 31, 2026 09:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant