From 35751b072a3b90a93e11313f1df0cf9a1f336613 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Sun, 6 Sep 2026 00:51:57 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Move=20the=20docs=20sources=20be?= =?UTF-8?q?side=20conf.py,=20so=20Read=20the=20Docs=20can=20build=20them?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs/conf.py` sat next to `docs/source/**`, and the build bridged the gap with `sphinx-build ... -c docs docs/source docs/_build/html`. Read the Docs has no `-c`: it builds `sphinx.configuration`'s directory as the source directory, so it would take `docs/` -- a directory holding one `index`-less `conf.py` -- and produce nothing. This is the same finding that reshaped sphinx-mounts' docs before its import. `docs/source/*` moves up to `docs/*` with `git mv`, so `git log --follow` and `git blame` keep working, and the `-c` goes: `tox -e docs-clean` now runs `sphinx-build -nW --keep-going -b html docs docs/_build/html`, which is character for character what Read the Docs runs by itself. `gh_pages.yml` needs no change -- it uploads `docs/_build/html`, which has not moved. `conf.py` loses the `source/` prefix from `html_favicon`, `html_static_path`, `templates_path` and furo's `source_directory`. With `docs/` as the source directory, the build output and the shared `ubproject.toml` are now inside it, so `exclude_patterns` names them (the dead `templates_path = ["_templates"]` line one directive above it, overwritten further down the file, goes at the same time). `quickstart.rst`'s two `literalinclude` paths lose one `../`; they were reaching out of `docs/source/basics/` to the repository root, and without the fix `-nW` fails on them. The `docs` requirements move from a dependency group to a `docs` **extra**. Read the Docs installs extras -- `python.install`'s `extra_requirements` -- and has no way at all to install a PEP 735 group. It is also the shape a member of the sphinx-needs workspace has, where the root re-exports each member's extra. The tox docs environments follow, from `dependency_groups = docs` to `extras = docs`. `furo` stays in `testing` as well: `tests/data/sphinx/conf.py` sets `html_theme = "furo"` and `test_src_trace.py` builds that project. A `.readthedocs.yaml` comes with it, modelled on sphinx-mounts': ubuntu-24.04, python 3.13, `sphinx.configuration: docs/conf.py`, `fail_on_warning: true`, and a pip install of `.` with the `docs` extra. Its paths are relative to the repository root, and its header says so, because at import they gain a `packages/sphinx-codelinks/` prefix. No `post_checkout` job: cancelling builds for pull requests that miss the package only makes sense once several projects build out of one repository. --- .readthedocs.yaml | 38 ++++++++++++++++++ AGENTS.md | 19 ++++----- README.md | 2 +- .../_static/_templates/furo/side-github.html | 0 docs/{source => }/_static/favicon.ico | Bin docs/{source => }/_static/furo.css | 0 .../_static/sphinx-codelinks-logo_dark.svg | 0 .../_static/sphinx-codelinks-logo_light.svg | 0 docs/{source => }/basics/installation.rst | 0 docs/{source => }/basics/introduction.rst | 0 docs/{source => }/basics/local_link.mp4 | Bin docs/{source => }/basics/quickstart.rst | 4 +- docs/{source => }/components/analyse.rst | 0 docs/{source => }/components/cli.rst | 0 .../{source => }/components/configuration.rst | 0 docs/{source => }/components/directive.rst | 0 docs/{source => }/components/discover.rst | 0 docs/{source => }/components/features.rst | 0 docs/{source => }/components/oneline.rst | 0 docs/{source => }/components/write.rst | 0 docs/conf.py | 14 ++++--- docs/{source => }/development/change_log.rst | 9 +++++ .../{source => }/development/contributing.rst | 0 docs/{source => }/development/roadmap.rst | 0 .../{source => }/development/traceability.rst | 0 docs/{source => }/index.rst | 0 pyproject.toml | 24 +++++++---- tox.ini | 12 +++--- 28 files changed, 91 insertions(+), 31 deletions(-) create mode 100644 .readthedocs.yaml rename docs/{source => }/_static/_templates/furo/side-github.html (100%) rename docs/{source => }/_static/favicon.ico (100%) rename docs/{source => }/_static/furo.css (100%) rename docs/{source => }/_static/sphinx-codelinks-logo_dark.svg (100%) rename docs/{source => }/_static/sphinx-codelinks-logo_light.svg (100%) rename docs/{source => }/basics/installation.rst (100%) rename docs/{source => }/basics/introduction.rst (100%) rename docs/{source => }/basics/local_link.mp4 (100%) rename docs/{source => }/basics/quickstart.rst (90%) rename docs/{source => }/components/analyse.rst (100%) rename docs/{source => }/components/cli.rst (100%) rename docs/{source => }/components/configuration.rst (100%) rename docs/{source => }/components/directive.rst (100%) rename docs/{source => }/components/discover.rst (100%) rename docs/{source => }/components/features.rst (100%) rename docs/{source => }/components/oneline.rst (100%) rename docs/{source => }/components/write.rst (100%) rename docs/{source => }/development/change_log.rst (95%) rename docs/{source => }/development/contributing.rst (100%) rename docs/{source => }/development/roadmap.rst (100%) rename docs/{source => }/development/traceability.rst (100%) rename docs/{source => }/index.rst (100%) diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..ddb238d7 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,38 @@ +# Read the Docs configuration for the sphinx-codelinks project. +# +# EVERY PATH BELOW IS RELATIVE TO THE REPOSITORY ROOT. That is true in this repository and +# will still be true after sphinx-codelinks is imported into the sphinx-needs uv workspace -- +# only the root will be a different one, so each path gains a `packages/sphinx-codelinks/` +# prefix at that point, and this file moves next to the package (the way +# `packages/sphinx-mounts/.readthedocs.yaml` already sits beside sphinx-mounts, with the RTD +# project's per-project "Build configuration file" setting pointing at it). +# +# Deliberately no `build.jobs.post_checkout`: that repository's mounts config cancels builds +# for pull requests that touch nothing under its package, which only makes sense once several +# projects build from one repository. Here there is one project and one repository. +version: 2 + +build: + # deliberately no `apt_packages`: these docs render no diagrams, so there is no `dot`, + # `java` or plantuml to install + os: ubuntu-24.04 + tools: + python: "3.13" + +sphinx: + # `docs/conf.py` is IN the source directory, so Read the Docs' own invocation + # (`sphinx-build -b html docs docs/_build/html`, with no `-c`) finds it -- which is why + # the sources were flattened up out of `docs/source/`. + configuration: docs/conf.py + builder: html + # the same strictness `tox -e docs-clean` and the ci.yml docs job use + fail_on_warning: true + +python: + install: + - method: pip + path: "." + extra_requirements: + # an extra rather than a dependency group: `python.install` has no way to install + # a PEP 735 group + - docs diff --git a/AGENTS.md b/AGENTS.md index d3505ae6..0d40bb25 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,13 +52,14 @@ tests/ # Test suite ├── __snapshots__/ # Syrupy snapshot test fixtures └── data/ # Test data and fixtures -docs/ # Documentation source (RST) -├── conf.py # Sphinx configuration -├── source/ -│ ├── index.rst # Documentation index -│ ├── basics/ # Basic usage documentation -│ ├── components/ # Component documentation -│ └── development/ # Development documentation +docs/ # Documentation source (RST) -- conf.py sits IN the source dir, +├── conf.py # so `sphinx-build docs docs/_build/html` needs no `-c` +├── ubproject.toml # Shared ubCode project file (needs + codelinks config) +├── index.rst # Documentation index +├── basics/ # Basic usage documentation +├── components/ # Component documentation +├── development/ # Development documentation +└── _static/ # Logos, favicon, furo overrides ``` ## Development Commands @@ -436,7 +437,7 @@ The CLI uses Typer for command definitions: ``` 2. Add tests in `tests/test_cmd.py` -3. Update documentation in `docs/source/components/cli.rst` +3. Update documentation in `docs/components/cli.rst` ### Adding Configuration Options @@ -444,7 +445,7 @@ The CLI uses Typer for command definitions: 2. Add validation if needed using Pydantic validators 3. Update TOML configuration examples in `docs/` and `tests/data/configs/` 4. Add tests for new configuration option -5. Document in `docs/source/components/configuration.rst` +5. Document in `docs/components/configuration.rst` ## Reference Documentation diff --git a/README.md b/README.md index 3c659575..62f35590 100644 --- a/README.md +++ b/README.md @@ -37,4 +37,4 @@ Full documentation: https://codelinks.useblocks.com ## Development -See [Development Guide](docs/source/development/) for contributing guidelines. +See [Development Guide](docs/development/) for contributing guidelines. diff --git a/docs/source/_static/_templates/furo/side-github.html b/docs/_static/_templates/furo/side-github.html similarity index 100% rename from docs/source/_static/_templates/furo/side-github.html rename to docs/_static/_templates/furo/side-github.html diff --git a/docs/source/_static/favicon.ico b/docs/_static/favicon.ico similarity index 100% rename from docs/source/_static/favicon.ico rename to docs/_static/favicon.ico diff --git a/docs/source/_static/furo.css b/docs/_static/furo.css similarity index 100% rename from docs/source/_static/furo.css rename to docs/_static/furo.css diff --git a/docs/source/_static/sphinx-codelinks-logo_dark.svg b/docs/_static/sphinx-codelinks-logo_dark.svg similarity index 100% rename from docs/source/_static/sphinx-codelinks-logo_dark.svg rename to docs/_static/sphinx-codelinks-logo_dark.svg diff --git a/docs/source/_static/sphinx-codelinks-logo_light.svg b/docs/_static/sphinx-codelinks-logo_light.svg similarity index 100% rename from docs/source/_static/sphinx-codelinks-logo_light.svg rename to docs/_static/sphinx-codelinks-logo_light.svg diff --git a/docs/source/basics/installation.rst b/docs/basics/installation.rst similarity index 100% rename from docs/source/basics/installation.rst rename to docs/basics/installation.rst diff --git a/docs/source/basics/introduction.rst b/docs/basics/introduction.rst similarity index 100% rename from docs/source/basics/introduction.rst rename to docs/basics/introduction.rst diff --git a/docs/source/basics/local_link.mp4 b/docs/basics/local_link.mp4 similarity index 100% rename from docs/source/basics/local_link.mp4 rename to docs/basics/local_link.mp4 diff --git a/docs/source/basics/quickstart.rst b/docs/basics/quickstart.rst similarity index 90% rename from docs/source/basics/quickstart.rst rename to docs/basics/quickstart.rst index d53a42d8..47bdab5a 100644 --- a/docs/source/basics/quickstart.rst +++ b/docs/basics/quickstart.rst @@ -37,14 +37,14 @@ Sphinx Config One-line comment ---------------- -.. literalinclude:: ./../../../tests/doc_test/minimum_config/dummy_src.cpp +.. literalinclude:: ./../../tests/doc_test/minimum_config/dummy_src.cpp :caption: dummy_src.cpp :language: cpp Directive --------- -.. literalinclude:: ./../../../tests/doc_test/minimum_config/index.rst +.. literalinclude:: ./../../tests/doc_test/minimum_config/index.rst :caption: index.rst :language: rst diff --git a/docs/source/components/analyse.rst b/docs/components/analyse.rst similarity index 100% rename from docs/source/components/analyse.rst rename to docs/components/analyse.rst diff --git a/docs/source/components/cli.rst b/docs/components/cli.rst similarity index 100% rename from docs/source/components/cli.rst rename to docs/components/cli.rst diff --git a/docs/source/components/configuration.rst b/docs/components/configuration.rst similarity index 100% rename from docs/source/components/configuration.rst rename to docs/components/configuration.rst diff --git a/docs/source/components/directive.rst b/docs/components/directive.rst similarity index 100% rename from docs/source/components/directive.rst rename to docs/components/directive.rst diff --git a/docs/source/components/discover.rst b/docs/components/discover.rst similarity index 100% rename from docs/source/components/discover.rst rename to docs/components/discover.rst diff --git a/docs/source/components/features.rst b/docs/components/features.rst similarity index 100% rename from docs/source/components/features.rst rename to docs/components/features.rst diff --git a/docs/source/components/oneline.rst b/docs/components/oneline.rst similarity index 100% rename from docs/source/components/oneline.rst rename to docs/components/oneline.rst diff --git a/docs/source/components/write.rst b/docs/components/write.rst similarity index 100% rename from docs/source/components/write.rst rename to docs/components/write.rst diff --git a/docs/conf.py b/docs/conf.py index 44d6690e..8a125640 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,8 +32,10 @@ "sphinxcontrib.video", ] -# exclude_patterns = [] -templates_path = ["_templates"] +# The source directory IS this directory, so the build output and the shared ubCode project +# file live inside it and have to be kept out of the document set. (`conf.py` itself is +# excluded by Sphinx.) +exclude_patterns = ["_build", "ubproject.toml", "Thumbs.db", ".DS_Store"] show_warning_types = True todo_include_todos = True @@ -51,19 +53,19 @@ html_title = "CodeLinks" html_theme = "furo" # original source is in ubdocs repo at docs/developer_handbook/design/files/ubcode_favicon/favicon.ico -html_favicon = "source/_static/favicon.ico" -html_static_path = ["source/_static"] +html_favicon = "_static/favicon.ico" +html_static_path = ["_static"] html_theme_options = { "sidebar_hide_name": True, "top_of_page_buttons": ["view", "edit"], "source_repository": "https://github.com/useblocks/sphinx-codelinks", "source_branch": "main", - "source_directory": "docs/source/", + "source_directory": "docs/", "light_logo": "sphinx-codelinks-logo_light.svg", "dark_logo": "sphinx-codelinks-logo_dark.svg", } -templates_path = ["source/_static/_templates/furo"] +templates_path = ["_static/_templates/furo"] html_sidebars = { "**": [ "sidebar/brand.html", diff --git a/docs/source/development/change_log.rst b/docs/development/change_log.rst similarity index 95% rename from docs/source/development/change_log.rst rename to docs/development/change_log.rst index 8b5a1c64..9b966146 100644 --- a/docs/source/development/change_log.rst +++ b/docs/development/change_log.rst @@ -33,6 +33,15 @@ New and Improved that workspace is tested on 3.11 against Sphinx 9, and this matrix is replaced by that one at import, so the combination is left unexercised here too, deliberately. +- 📚 The documentation sources moved up beside ``conf.py``, so Read the Docs can build them. + + ``docs/source/*`` is now ``docs/*``, and the docs build no longer passes ``-c``: + ``sphinx-build -nW --keep-going -b html docs docs/_build/html`` is what ``tox -e docs-clean`` + runs and what Read the Docs runs by itself. A ``.readthedocs.yaml`` comes with it, and the + ``docs`` requirements move from a dependency group to a ``docs`` extra, which is the only + form Read the Docs can install. The rendered site is unchanged; only the "edit this page" + links point at the new paths. + - ✨ The default configuration file is now ``ubproject.toml``. :ref:`src_trace_config_from_toml` now defaults to ``"ubproject.toml"`` and the diff --git a/docs/source/development/contributing.rst b/docs/development/contributing.rst similarity index 100% rename from docs/source/development/contributing.rst rename to docs/development/contributing.rst diff --git a/docs/source/development/roadmap.rst b/docs/development/roadmap.rst similarity index 100% rename from docs/source/development/roadmap.rst rename to docs/development/roadmap.rst diff --git a/docs/source/development/traceability.rst b/docs/development/traceability.rst similarity index 100% rename from docs/source/development/traceability.rst rename to docs/development/traceability.rst diff --git a/docs/source/index.rst b/docs/index.rst similarity index 100% rename from docs/source/index.rst rename to docs/index.rst diff --git a/pyproject.toml b/pyproject.toml index aef6fb92..b6826ae7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -56,6 +56,20 @@ dependencies = [ # stable since long before 16), so support older toolchains too. No upper bound. libclang = ["libclang>=16"] +# An EXTRA, not a dependency group, because Read the Docs installs extras and cannot install +# groups: its `python.install` block takes `extra_requirements`, and there is no equivalent +# for PEP 735 groups. It is also the shape a member of the sphinx-needs workspace has -- +# the root there re-exports each member's extra (`docs-mounts = ["sphinx-mounts[docs]"]`), +# because `uv sync --extra` resolves against the workspace root rather than the member. +docs = [ + "furo>=2024.5.6", + "myst-parser>=4.0.0", + "sphinx-design>=0.6.1", + "sphinx-code-tabs>=0.5.5", + "sphinxcontrib-typer>=0.5.1,<0.9.1", # 0.9.1 imports typer.rich_utils.STYLE_TYPES, absent in the capped typer <0.26.8, breaking the docs build + "sphinxcontrib-video>=0.4.1", +] + [build-system] requires = ["flit_core >=3.4,<4"] build-backend = "flit_core.buildapi" @@ -69,17 +83,11 @@ testing = [ "psutil>=7.0.0", "moto ~= 5.0", "toml>=0.10.2", + # not a docs dependency here: tests/data/sphinx and tests/data/needextend_demo set + # `html_theme = "furo"`, and test_src_trace.py builds the first of them "furo>=2024.5.6", "libclang>=18", ] -docs = [ - "furo>=2024.5.6", - "myst-parser>=4.0.0", - "sphinx-design>=0.6.1", - "sphinx-code-tabs>=0.5.5", - "sphinxcontrib-typer>=0.5.1,<0.9.1", # 0.9.1 imports typer.rich_utils.STYLE_TYPES, absent in the capped typer <0.26.8, breaking the docs build - "sphinxcontrib-video>=0.4.1", -] mypy = [ "mypy>=1.12.1", "pydantic ~= 2.9", diff --git a/tox.ini b/tox.ini index 3e732082..54b8ea6e 100644 --- a/tox.ini +++ b/tox.ini @@ -47,24 +47,26 @@ commands = pytest {posargs} [testenv:docs-{update,clean}] description = Build documentation with Sphinx -dependency_groups = docs +# an EXTRA, not a group: Read the Docs installs extras and has no way to install a +# dependency group, so the docs requirements have to live where RTD can reach them +extras = docs allowlist_externals = rm passenv = BUILDER TERM commands = clean: rm -rf docs/_build/{env:BUILDER:html} - sphinx-build -nW --keep-going -b {env:BUILDER:html} -T -c docs docs/source docs/_build/{env:BUILDER:html} {posargs} + sphinx-build -nW --keep-going -b {env:BUILDER:html} -T docs docs/_build/{env:BUILDER:html} {posargs} [testenv:docs-live] description = Build the documentation and launch browser deps = sphinx-autobuild -dependency_groups = docs +extras = docs commands = sphinx-autobuild \ --re-ignore _build/.* \ --port 0 --open-browser \ - -n -b {posargs:html} -c docs docs/source docs/_build/{posargs:html} + -n -b {posargs:html} docs docs/_build/{posargs:html} [testenv:mypy] dependency_groups = mypy @@ -82,7 +84,7 @@ commands = ruff format {posargs} [testenv:demo] description = Run the needextend demo (analyse, write, build) -dependency_groups = docs +extras = docs allowlist_externals = rm commands = rm -rf tests/data/needextend_demo/_build