useblocks · chrisjsewell · Sep 6, 2026 · Sep 5, 2026
diff --git a/.readthedocs.yaml 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
@@ -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,15 +437,15 @@ 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
 
 1. Add field to `AnalyseConfig` or relevant Pydantic model in `config.py`
 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
@@ -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/.../_static/_templates/furo/side-github.html → .../_static/_templates/furo/side-github.html b/.../_static/_templates/furo/side-github.html → .../_static/_templates/furo/side-github.html
diff --git a/docs/source/_static/favicon.ico → docs/_static/favicon.ico b/docs/source/_static/favicon.ico → docs/_static/favicon.ico
diff --git a/docs/source/_static/furo.css → docs/_static/furo.css b/docs/source/_static/furo.css → docs/_static/furo.css
diff --git a/...ce/_static/sphinx-codelinks-logo_dark.svg → docs/_static/sphinx-codelinks-logo_dark.svg b/...ce/_static/sphinx-codelinks-logo_dark.svg → docs/_static/sphinx-codelinks-logo_dark.svg
diff --git a/...e/_static/sphinx-codelinks-logo_light.svg → docs/_static/sphinx-codelinks-logo_light.svg b/...e/_static/sphinx-codelinks-logo_light.svg → docs/_static/sphinx-codelinks-logo_light.svg
diff --git a/docs/source/basics/installation.rst → docs/basics/installation.rst b/docs/source/basics/installation.rst → docs/basics/installation.rst
diff --git a/docs/source/basics/introduction.rst → docs/basics/introduction.rst b/docs/source/basics/introduction.rst → docs/basics/introduction.rst
diff --git a/docs/source/basics/local_link.mp4 → docs/basics/local_link.mp4 b/docs/source/basics/local_link.mp4 → docs/basics/local_link.mp4
diff --git a/docs/source/basics/quickstart.rst → docs/basics/quickstart.rst b/docs/source/basics/quickstart.rst → 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 → docs/components/analyse.rst b/docs/source/components/analyse.rst → docs/components/analyse.rst
diff --git a/docs/source/components/cli.rst → docs/components/cli.rst b/docs/source/components/cli.rst → docs/components/cli.rst
diff --git a/docs/source/components/configuration.rst → docs/components/configuration.rst b/docs/source/components/configuration.rst → docs/components/configuration.rst
diff --git a/docs/source/components/directive.rst → docs/components/directive.rst b/docs/source/components/directive.rst → docs/components/directive.rst
diff --git a/docs/source/components/discover.rst → docs/components/discover.rst b/docs/source/components/discover.rst → docs/components/discover.rst
diff --git a/docs/source/components/features.rst → docs/components/features.rst b/docs/source/components/features.rst → docs/components/features.rst
diff --git a/docs/source/components/oneline.rst → docs/components/oneline.rst b/docs/source/components/oneline.rst → docs/components/oneline.rst
diff --git a/docs/source/components/write.rst → docs/components/write.rst b/docs/source/components/write.rst → docs/components/write.rst
diff --git 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 → docs/development/change_log.rst b/docs/source/development/change_log.rst → 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 → docs/development/contributing.rst b/docs/source/development/contributing.rst → docs/development/contributing.rst
diff --git a/docs/source/development/roadmap.rst → docs/development/roadmap.rst b/docs/source/development/roadmap.rst → docs/development/roadmap.rst
diff --git a/docs/source/development/traceability.rst → docs/development/traceability.rst b/docs/source/development/traceability.rst → docs/development/traceability.rst
diff --git a/docs/source/index.rst → docs/index.rst b/docs/source/index.rst → docs/index.rst
diff --git 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
@@ -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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.