From ece86ac6b7d888866ca7329f9e53916157dcf36b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Picault?= Date: Mon, 31 Aug 2026 11:06:00 +0200 Subject: [PATCH] Make the Read the Docs build work MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .readthedocs.yaml | 24 +++++++++++------------- README.md | 4 ++-- docs/_static/.gitkeep | 0 docs/conf.py | 39 +++++++++++++++++++++++++++++++++++++++ docs/index.md | 14 ++++++++++++++ docs/requirements.txt | 5 +++++ 6 files changed, 71 insertions(+), 15 deletions(-) create mode 100644 docs/_static/.gitkeep create mode 100644 docs/conf.py create mode 100644 docs/index.md create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 7a30f29..30dab78 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,26 +1,24 @@ - - # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details -# Required version: 2 -# Set the OS, Python version, and other tools you might need build: os: ubuntu-24.04 tools: python: "3.13" -# Build documentation in the "docs/" directory with Sphinx sphinx: - configuration: docs/conf.py + configuration: docs/conf.py + # Keep builds strict-ish without failing on the odd cross-file link. + fail_on_warning: false -# Optionally, but recommended, -# declare the Python requirements required to build your documentation -# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt - +# HTML only: the mermaid diagrams need a headless browser to rasterize, which +# the PDF/epub builders don't have on Read the Docs. +formats: [] +# Only the doc toolchain is installed — the docs are prose, so ConfLens itself +# (and its heavy LLM / NiceGUI deps) is never imported at build time. +python: + install: + - requirements: docs/requirements.txt diff --git a/README.md b/README.md index 700b4e3..4a6fd8f 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![Stars](https://img.shields.io/github/stars/picaultj/conflens?logo=github&style=flat)](https://github.com/picaultj/conflens/stargazers) [![Last commit](https://img.shields.io/github/last-commit/picaultj/conflens?logo=github)](https://github.com/picaultj/conflens/commits/main) [![Issues](https://img.shields.io/github/issues/picaultj/conflens?logo=github)](https://github.com/picaultj/conflens/issues) -[![License: MPL 2.0](https://img.shields.io/badge/license-MPL%202.0-brightgreen.svg)](LICENSE) +[![License: MPL 2.0](https://img.shields.io/badge/license-MPL%202.0-brightgreen.svg)](https://github.com/picaultj/conflens/blob/main/LICENSE) [![uv](https://img.shields.io/badge/managed%20by-uv-DE5FE9.svg?logo=uv&logoColor=white)](https://docs.astral.sh/uv/) [![Built with NiceGUI](https://img.shields.io/badge/UI-NiceGUI-2b6cb0.svg)](https://nicegui.io) @@ -77,7 +77,7 @@ ways: plus `OPENAI_BASE_URL` for an OpenAI-compatible endpoint; `LITELLM_API_KEY`). - **A `.env` file** in the directory you launch `conflens` from — same keys, one `NAME=value` per line. It's loaded automatically from the current working - directory (from a clone, copy [`.env.example`](.env.example) as a starting + directory (from a clone, copy [`.env.example`](https://github.com/picaultj/conflens/blob/main/.env.example) as a starting point). Real environment variables take precedence over `.env`. - **The in-app “API key” field** at runtime. diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..170b071 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,39 @@ +"""Sphinx configuration for the ConfLens documentation. + +The docs are plain Markdown (rendered through MyST), so this build never +imports ConfLens itself — no LLM/NiceGUI dependencies are needed on Read the +Docs. The version is read straight from ``pyproject.toml`` to keep it in sync +with the release that `release.yml` bumps. +""" + +import tomllib +from pathlib import Path + +_pyproject = tomllib.loads( + (Path(__file__).parent.parent / "pyproject.toml").read_text(encoding="utf-8") +) + +project = "ConfLens" +author = _pyproject["project"]["authors"][0]["name"] +copyright = f"2025, {author}" # noqa: A001 - Sphinx expects this name +release = _pyproject["project"]["version"] +version = ".".join(release.split(".")[:2]) + +extensions = ["myst_parser", "sphinxcontrib.mermaid"] + +exclude_patterns = ["_build", "requirements.txt", "Thumbs.db", ".DS_Store"] + +# -- MyST --------------------------------------------------------------------- +# `colon_fence` lets directives be written as ::: blocks; heading anchors make +# the README's in-page "Contents" links (#quick-start, ...) resolve. +myst_enable_extensions = ["colon_fence", "deflist", "linkify", "substitution"] +myst_heading_anchors = 3 + +# Render GitHub-style ```mermaid fences (used throughout ARCHITECTURE.md and the +# README) through sphinxcontrib-mermaid instead of trying to syntax-highlight them. +myst_fence_as_directive = ["mermaid"] + +# -- HTML --------------------------------------------------------------------- +html_theme = "furo" +html_title = f"{project} {release}" +html_static_path = ["_static"] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..8a386ee --- /dev/null +++ b/docs/index.md @@ -0,0 +1,14 @@ +# ConfLens + +```{toctree} +:maxdepth: 2 +:hidden: + +ARCHITECTURE +``` + +```{include} ../README.md +:start-line: 1 +:relative-docs: docs/ +:relative-images: +``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..5048cee --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +# Documentation toolchain for the Read the Docs build (see ../.readthedocs.yaml). +sphinx>=8.1 +myst-parser[linkify]>=4.0 +sphinxcontrib-mermaid>=1.0 +furo>=2024.8.6