📚 Move the docs sources beside conf.py, so Read the Docs can build them

[chrisjsewell]

docs/conf.py sits next to docs/source/**, and the build bridges the gap with
sphinx-build … -c docs docs/source docs/_build/html. Read the Docs has no -c. It takes
the directory of sphinx.configuration as the source directory, so it would build docs/ — a
directory containing one conf.py and no index — and produce nothing. This is the same
finding that reshaped sphinx-mounts' documentation before it was imported into the sphinx-needs
repository, and it is the reason this repository cannot move off GitHub Pages as it stands.

So docs/source/* moves up into docs/*, with git mv, so git log --follow and git blame
keep working; 23 files, all recorded as renames. The -c goes with it:
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 on its own. gh_pages.yml is untouched
— it uploads docs/_build/html, which has not moved — so Pages keeps working until someone
chooses to turn it off.

conf.py loses the source/ prefix from html_favicon, html_static_path, templates_path
and furo's source_directory. Because docs/ is now the source directory, the build output and
the shared ubproject.toml sit inside it, so exclude_patterns names them; the dead
templates_path = ["_templates"] line (overwritten twelve lines further down) goes at the same
time. quickstart.rst's two literalinclude paths lose one ../ — they were climbing out of
docs/source/basics/ to the repository root, and -nW fails on them otherwise.

The docs requirements become an extra rather than a dependency group. Read the Docs
installs extras — that is what python.install's extra_requirements is — and has no way at
all to install a PEP 735 group, so requirements in a group are simply unreachable from RTD. It
is also the shape a member of the sphinx-needs workspace has, where the root re-exports each
member's extra. The three tox environments that used the group switch to extras = docs.
furo stays in testing too, deliberately: tests/data/sphinx/conf.py sets
html_theme = "furo" and test_src_trace.py builds that project.

Finally, a .readthedocs.yaml at the repository root, modelled on the one sphinx-mounts
carries: ubuntu-24.04, python 3.13, fail_on_warning: true, and a pip install of . with the
docs extra. No apt_packages — these docs render no diagrams — and deliberately no
post_checkout skip job, which only earns its keep once several RTD projects build out of one
repository. Its header records that every path in it is relative to the repository root, so at
import they each gain a packages/sphinx-codelinks/ prefix.

How to verify

tox -e docs-clean
# and the RTD-shaped build, from nothing but the extra:
uv venv /tmp/cl-docs && uv pip install --python /tmp/cl-docs/bin/python '.[docs]'
/tmp/cl-docs/bin/sphinx-build -nW --keep-going -b html docs docs/_build/rtd
git diff --stat -M      # renames, not delete + add

Both builds are green locally (docs-clean 8 s; the RTD-shaped one exits 0).

Out of scope: creating the Read the Docs project itself and pointing
codelinks.useblocks.com at it (Chris/Marco, after the import); turning off the GitHub Pages
deployment; prefixing the historical tags; removing [dependency-groups], [tool.pytest] or
tests/__init__.py; the PyPI trusted publisher; release.yaml; the pre-commit → prek switch;
and any behaviour change to the extension.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.91%. Comparing base (1d06369) to head (35751b0).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #104   +/-   ##
=======================================
  Coverage   92.91%   92.91%           
=======================================
  Files          44       44           
  Lines        3770     3770           
  Branches      381      381           
=======================================
  Hits         3503     3503           
  Misses        157      157           
  Partials      110      110           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.