✨🔧💡 Proposal: evolving sphinx-needs into a monorepo

[chrisjsewell]

Summary

We are considering restructuring this repository into a monorepo that can also host
sibling extensions from the useblocks org. The initial candidates are:

• sphinx-codelinks
• sphinx-mounts
• sphinx-test-reports

— though neither the list nor the timing is fixed: the restructuring is useful for
sphinx-needs on its own, extensions can move over one at a time as they are ready
(sphinx-test-reports, for example, needs the most modernisation and may follow later
without blocking anything), and other extensions could join the same way in future.

To be clear up front: this is about where the code lives and how it is developed and
tested — not about merging the packages themselves.

We've done a fairly deep investigation of the mechanics (uv workspaces, testing matrices,
Read the Docs, releases, history migration) including hands-on verification of the
sharp edges, and studied how comparable projects run the same shape. This post lays out
the motivation, the proposed design, and the open questions we'd like feedback on before
committing.

What changes for users — and what doesn't

Doesn't change: the PyPI packages, their names, their independent versions and
release cadences, how you install them, and the documentation content and URLs.

Changes: where issues and PRs live (here, with package: labels), tag names, the
extensions' sphinx-needs policy — a new sphinx-codelinks/mounts/test-reports release
will require the sphinx-needs version current at that release (question 2 below) — and
possibly the supported Python floor (question 1).

Why

These extensions are all tightly coupled to sphinx-needs, and the separate-repo setup
makes that coupling expensive:

• We can't see breakage when it happens. A sphinx-needs change that breaks
  sphinx-codelinks or sphinx-test-reports is only discovered when their CI next runs
  against a released sphinx-needs. sphinx-mounts currently resorts to a documented
  workaround — git-pinning sphinx-needs@master in its test dependencies — just to test
  against unreleased changes. In a monorepo, every sphinx-needs PR runs the extensions'
  tests against that PR.
• Duplicated logic. sphinx-mounts deliberately vendors a copy of sphinx-needs'
  variant-data handling (documented in its source, kept behaviourally identical by hand)
  rather than depending on it. In one repo, extracting genuinely shared code — its source
  literally anticipates a shared sphinx-variants package — becomes a git mv instead
  of a cross-repo coordination problem. (One caveat: the variant expression grammar is
  also mirrored by ubCode's engine, so any extraction needs to treat that contract with
  care.)
• Core changes that serve the extensions are hard to land. Things like letting
  sphinx-codelinks store the origin of needs it creates require coordinated changes in
  two repos today; in one repo they are a single PR whose tests cover both sides
  immediately.
• Four of everything, drifting. Four CI setups, four lint/type configs, four
  supported-version matrices. They have already diverged: Python floors are 3.10 in two
  repos and 3.12 in the other two, ruff pins span three versions, sphinx-needs still
  publishes with an API token while the other three use trusted publishing, and
  sphinx-test-reports declares a sphinx-needs>=1.0.1 floor that is ~7 majors stale.
  One repo means one set of supported Sphinx/Python versions, tested together.

Proposed shape

Built on uv workspaces, which
we've verified against this exact topology (a core package + dependent extensions):

sphinx-needs/                      # this repository
├── pyproject.toml                 # workspace root (not itself a package): members,
│                                  #   shared lint groups, test-matrix config, poe tasks
├── uv.lock                        # one shared lockfile
├── .pre-commit-config.yaml        # shared hygiene hooks (see prek below)
├── scripts/                       # install smoke checks + release glue (run via poe tasks)
└── packages/
    ├── sphinx-needs/              # each with its own pyproject.toml, tests/, docs/
    ├── sphinx-codelinks/          #   and its own hook config
    ├── sphinx-mounts/
    └── sphinx-test-reports/

The mechanism that makes independent releases work: each extension declares a real
version range on sphinx-needs in [project.dependencies] — that is exactly what ships
in its published wheel — plus a uv-only redirect that makes local development and CI use
the in-tree sphinx-needs:

[project]
dependencies = ["sphinx-needs>=8.4,<9"]   # what users get from PyPI

[tool.uv.sources]
sphinx-needs = { workspace = true }        # what developers/CI get: the local checkout

uv sync --all-packages gives every contributor (and every coding agent) all four
packages editable in one command, and an edit in sphinx-needs is immediately visible to
the extensions' tests with no reinstall step.

Tooling consolidation

The four repos are really three generations of the same house style, and the merge is
the moment to converge on the newest one (which sphinx-codelinks and sphinx-mounts
already share):

• prek instead of pre-commit. prek is a drop-in,
  much faster reimplementation, and its
  workspace mode is what makes a multi-package repo
  tractable: each package keeps its own .pre-commit-config.yaml, unmodified, with
  hooks running relative to that package — no root config smeared with per-package
  files: regexes. sphinx-mounts has already run prek in CI for months; every hook
  currently used across the four repos is supported.
• One ruff ruleset, staged. sphinx-codelinks and sphinx-mounts already have
  byte-identical ruff configs; that becomes the shared root config. sphinx-needs and
  sphinx-test-reports adopt it via ruff's extend mechanism with temporary per-package
  ignores that get retired family-by-family (measured honestly: sphinx-needs is ~580
  findings away from the shared ruleset, so this is a tracked backlog, not a big bang).
• mypy stays the type gate for now; ty runs alongside.
  sphinx-mounts is already ty-only; for sphinx-needs, ty is ~80× faster than mypy but
  still pre-1.0 with unstable diagnostics, and sphinx-codelinks depends on the
  pydantic.mypy plugin which ty has no equivalent for yet. So: keep mypy blocking,
  add ty as a non-blocking job, revisit at ty 1.0.
• One pytest config at the root (with --import-mode=importlib — required, since
  four Sphinx-extension packages will inevitably have colliding test_*.py basenames).
• poe as the single task runner, replacing the
  current tox / nox / Makefile mix. Tasks live in [tool.poe.tasks] in the root
  pyproject and run as uv run poe … — nothing extra to install after uv sync, and
  the entry points (poe test <package>, poe docs <package>, poe smoke <package>)
  are the same everywhere, for humans and coding agents alike.

Testing

A monorepo quietly inverts today's testing contract: sphinx-codelinks and
sphinx-test-reports currently prove compatibility against a range of released
sphinx-needs versions (36-combination matrices), while a monorepo tests everything
against the in-tree sphinx-needs. Rather than fight that, we propose to embrace it as
policy (see Releases: the extensions track the latest sphinx-needs). The wide
released-version matrices are then retired outright — sphinx-test-reports'
six-pinned-versions nox matrix gets deleted, not ported — and testing becomes:

1. In-workspace (replaces tox): every package × Python × Sphinx, always against the
   in-tree sphinx-needs — so a sphinx-needs PR that breaks an extension fails that PR.
   Matrix cells are expressed as
   PEP 735 dependency groups plus uv's conflicts
   table, which means every matrix cell is locked and reproducible — an improvement
   over tox, where each env re-resolves against live PyPI.
   sphinx-contrib/typer already ships exactly
   this pattern in production. The local workflow tox provides today survives intact:
   one command runs one cell (poe cell sphinx-codelinks 3.12 sphinx8), each cell keeps
   its own persistent venv so re-runs are as fast as tox's cached envs, and a red CI
   cell reproduces locally with the identical command. (Anyone attached to tox -p
   parallel sweeps can keep a thin tox.ini as a purely local frontend via tox-uv's
   lock-runner — the one tox configuration that is safe inside a workspace.)
2. Install smoke checks (out-of-workspace): each extension's built wheel installed
   from its plain published metadata (--no-sources) against PyPI, imported, and
   minimally exercised. Small but load-bearing: uv never checks that declared dependency
   ranges are satisfiable by anything actually on PyPI, and inside the workspace the
   local sphinx-needs silently satisfies everything. (We verified the sharp edges here
   carefully — including that tox with tox-uv inside a workspace substitutes the local
   package for the released one it claims to install, which is why these checks run
   outside the workspace.) After a coordinated release this same check also proves the
   declared floor, since the floor is the just-released version.

Documentation

Each package keeps its own docs build and its own versioned documentation site.
Read the Docs supports multiple projects building from one repository (per-project
config paths + automation rules that only trigger a build when that package's files
change). sphinx-codelinks and sphinx-mounts — currently unversioned GitHub Pages sites —
would gain versioned docs in the process. Existing URLs are preserved or redirected;
in particular sphinx-needs.readthedocs.io (including objects.inv, which other
projects' intersphinx builds depend on) stays reachable.

A possible later step — grouping all four under one docs domain with shared search
(RTD subprojects) — is explicitly not part of this proposal and would be discussed
separately.

Releases

• Independent versions, package-prefixed tags: sphinx-needs-v8.5.0,
  sphinx-codelinks-v1.5.0, … (today all four repos use bare X.Y.Z tags — eight of
  which literally collide between repos).
• One release workflow publishing via PyPI trusted publishing (a single workflow is
  explicitly supported as the publisher for multiple PyPI projects). sphinx-needs moves
  from its current API-token setup to trusted publishing as part of this.
• The extensions track the latest sphinx-needs. At every extension release, its
  requirement is set mechanically to sphinx-needs>=<current>,<next major> — exactly
  the version it was developed and tested against. The extensions never carry
  backward-compatibility code; and because the cap sits at the major rather than an
  exact pin, users can still upgrade sphinx-needs freely within a major without
  waiting for extension re-releases. (This applies where a runtime dependency exists —
  sphinx-codelinks and sphinx-test-reports today; sphinx-mounts deliberately has none.)
  One consequence to own: when a sphinx-needs major ships, the <next major> caps
  hold users back until the extensions re-release — so a core major is followed by a
  prompt re-release train of the extensions, which the release workflow can do in one
  run.
• Needs-first release ordering. One release workflow, package as input. Releasing an
  extension first runs its test suite against the latest released sphinx-needs: green
  means the extension ships with that as its floor and no core release is forced (so
  unfinished work on sphinx-needs master never gets pushed out early by an unrelated
  extension fix). Red means the extension depends on unreleased sphinx-needs changes —
  the workflow then releases sphinx-needs first, waits until PyPI serves it, raises the
  extension's floor, and releases the extension.
  mcbeet/beet runs the core-first loop today
  (core first, dependants after, floors bumped in between).
• Per-package changelogs stay where they are (each package's docs); per-package GitHub
  releases, with filtered release listings per package.

History, issues, and the old repos

• The three repos are imported with git filter-repo, rewriting paths into
  packages/<name>/ — so git log and git blame on the moved files keep their full
  history (most projects that did similar merges dropped history; we'd rather not).
  Issue references in imported commit messages are rewritten to their fully-qualified
  form (useblocks/sphinx-codelinks#123) so they keep pointing at the right thing.
• Open issues are transferred to this repo (GitHub redirects the old URLs) with
  package: labels; open PRs unfortunately cannot be transferred and would be closed
  with a note inviting re-opening here (~18 across the three repos).
• The old repos are archived read-only, never deleted — every existing link, commit
  URL, and release keeps working.

Prior art

Projects we studied that run this shape today, and what we'd take from each:

Project	Shape	What we'd copy
apache/airflow	core + ~100 providers, one uv workspace, independent releases	overall structure; per-package docs/ with own conf.py; parameterised contributor/agent docs
langchain-ai/langchain	core + partner packages, independent versions	release ordering (PyPI first, then tag/release), fail-closed "already published?" checks, change-detection CI that fans a core change out to dependants
dbt-labs/dbt-adapters	core + 8 adapters	CI path-filtering and per-package changelog machinery sized for a handful of packages
mcbeet/beet	core + 3 dependent extensions (closest match)	the release loop: per-package version bump + automatic floor propagation from one workflow
sphinx-contrib/typer	single package, Sphinx matrix	the locked Sphinx-version test matrix via dependency groups
swyddfa/esbonio	2 independently-versioned dists, one repo	the only real Sphinx-ecosystem precedent

For honesty's sake: the Sphinx ecosystem has historically gone the other way
(sphinx-contrib once had a monorepo and split it into per-extension repos). The
difference that makes us optimistic: the ecosystems where monorepos work well (airflow,
langchain, dbt) all share our situation — one team maintaining and releasing the core
and its extensions together — whereas sphinx-contrib was many unrelated maintainers
sharing a repo.

Open questions (feedback wanted)

1. Python floor. A uv workspace enforces one requires-python across members — the
   intersection of today's metadata is >=3.12 (sphinx-codelinks and sphinx-mounts are
   already 3.12+). Aligning everything at >=3.12 alongside a sphinx-needs 9.0 would
   be the clean answer, especially with Python 3.10 reaching end-of-life in October 2026
   and Sphinx 9 itself requiring 3.12. Would dropping Python 3.10/3.11 support in the
   next sphinx-needs major be a problem for your setups?
2. How much old-sphinx-needs compatibility do the extensions need? This proposal
   sets each extension release to require the sphinx-needs it was built against
   (upgradeable within the major), in exchange for zero compatibility shims and instant
   use of new sphinx-needs APIs. If you rely on running sphinx-codelinks or
   sphinx-test-reports against an older, pinned sphinx-needs — including if you
   re-package these for conda or a Linux distribution — tell us; that is the one
   workflow this policy trades away. (For honesty: today's wide ranges are partly
   nominal anyway — sphinx-test-reports declares sphinx-needs>=1.0.1, which no CI has
   tested for years.)
3. Repository name. Keep useblocks/sphinx-needs (GitHub redirects mean nothing
   breaks) or rename to reflect the wider scope?
4. Issue migration. Transfer all open issues from the three repos here, or triage
   first and transfer selectively?
5. Anything we've missed that would make this worse for you as a user or contributor —
   or other extensions you think should join the monorepo (or candidates listed here
   that you think shouldn't)?

Proposed first steps

Nothing structural lands until the questions above settle. The early steps are
deliberately non-disruptive — each is useful even if the monorepo never happens:

Step 1 — converge the tooling in place (independent PRs, per repo):

• sphinx-needs: switch pre-commit → prek (following sphinx-mounts' setup), unify the
  ruff version across config and hooks, move the package version from
  __init__.py to static pyproject.toml metadata, and switch PyPI publishing from the
  API token to trusted publishing.
• sphinx-test-reports: fix the stale floors (sphinx-needs>=1.0.1, unbounded
  sphinx>4.0), modernise the CI actions, and align its lint/type setup with the others.
• sphinx-codelinks: bump the ruff pin; add the missing [project.urls] metadata.
• all: agree the shared ruff ruleset and land the version-pin unification separately
  from any ruleset changes (two distinct churn sources; conflating them makes review
  impossible).

Step 2 — add the install smoke checks:

• each extension's built wheel installed from plain published metadata against PyPI and
  import-tested, in each repo's CI. Cheap now, and it is the guard that stays honest
  once the monorepo makes in-tree testing the default.

Step 3 — rehearse on this repo alone:

• restructure sphinx-needs into the workspace layout (packages/sphinx-needs/ + a
  workspace root, root pytest config, prek workspace mode) while it is still the only
  package. Low risk, and it shakes out the tooling with no other package involved.

Step 4 — import incrementally, smallest first:

• sphinx-mounts (newest, already on prek/ty/uv — and its git-pin workaround disappears
  on arrival), then sphinx-codelinks; each via git filter-repo with prefixed tag
  renames, followed by its issue transfer and docs wiring — and each import stands on
  its own, so a package that isn't ready simply stays where it is for now.
  sphinx-test-reports carries the most modernisation work and can follow whenever it is
  ready without blocking any of the above. Re-register each PyPI trusted publisher for
  the new workflow before that package's first monorepo release.

Comments very welcome — especially from anyone maintaining downstream tooling or CI that
pins these packages, and from contributors on whether the monorepo makes your workflow
better or worse.

[ubmarco]

My 5 cents:

• Python 3.9 is unsupported, and the Sphinx-Needs 6 release dropped that version. That would be my minimum floor.
• We might want to factor out shared utilities into a dedicated package, such as the logging/warning system, to be used by all participants of the monorepo.
• SN could expose optional dependencies, so you can install it via sphinx-needs[codelinks, test-reports] as a single dependency.

[chrisjsewell]

Progress update, as of the 8.5.0 release

The groundwork phase of this proposal is done. Everything below is in master and in 8.5.0, and none of it changes the published package; it is the tooling the workspace needs, landed in sphinx-needs first so the move itself becomes a directory rename rather than a rewrite.

Shipped

• prek instead of pre-commit (🔧 Switch the lint runner from pre-commit to prek #1804). Workspace mode is what lets each package keep its own hook config once there are several; pre-commit.ci is retired, and a scheduled workflow opens a monthly prek update PR through an org GitHub App (🔧 Add a scheduled prek update workflow #1806), running the hooks first so the PR arrives green.
• One ruff / mypy version everywhere, with the rule set pinned (🔧 Unify the ruff and mypy pins, and pin the rule set that goes with them #1805): ruff 0.16 replaced its default rules, and the repository relied on the default, so the selection is now explicit.
• uv.lock is committed (🔧 Track uv.lock, and pin CI's uv commands to it #1807), a uv-lock hook keeps it current, and every CI command runs --frozen. Dependabot manages the lock monthly: minor and patch bumps batched, majors one PR each, sphinx series bumps ignored because the test matrix pins them on purpose (⬆️ Absorb the open dependabot PRs, and unblock their CI #1819 and the queue behind it).
• tox is gone; poe is the task runner, and the sphinx matrix is dependency groups (🔧 Run the sphinx matrix from the lock, and retire tox for poe #1823). sphinx-7/8/9 are groups in one uv conflict set, each CI cell syncs its group from the lock, and every contributor command is uv run poe <task>, with trailing arguments passed through to pytest. This is the shape the workspace needs: root tasks, per-package tasks with cwd, package-prefixed group names.
• mypy is replaced by ty (🔧 Replace mypy with ty for type checking #1830). The type-checking floor, the oldest supported sphinx and docutils plus the stubs, is a typing dependency group installed into .venvs/typing; ty's own version is in the lock; the editor extension sees the same environment as the gate. Measured before deciding: zero diagnostic churn across seven ty releases on this tree, the suppression rewrite is one command, and ty found a real bug mypy could not see. sphinx-mounts is already ty-only and the other two packages are a short port away, so the workspace gets one checker.
• The benchmark workflow runs again (🔧 Exempt third-party node classes from the test-suite parent check, so the benchmark runs again #1832), red since July on a sphinx-design node-hygiene quirk.

Decisions taken along the way (details in the linked PRs): a virtual workspace root with packages/<dist-name>/; extensions track the latest sphinx-needs with an eager floor and a major cap, released needs-first; the Python floor moves to 3.11 with the next major only; the released-version compatibility check becomes an out-of-workspace wheel-install cell rather than a poe task.

Next

1. The directory move itself: packages/sphinx-needs/, the virtual root, poe tasks moved up, and the Read the Docs, release, docker and benchmark paths that follow. The recon for it also has to measure how ty resolves the local sibling package for a dependant (editable install versus extra-paths) and what the workspace's requires-python intersection is once a ≥3.12 member joins.
2. The imports, one at a time and each standalone: sphinx-mounts first (smallest, newest, already on prek/ty/uv), then sphinx-codelinks, then sphinx-test-reports.
3. The release arc before the first workspace release: the needs-first gate, tag scheme <dist>-v<version>, one trusted-publishing workflow.

Open threads that are not blocking: #1829 (nothing tests the built package), #1835 (the ty suppressions to burn down), #1725 (the data.py dynamic-attribute surface), and a dead pydantic-mypy configuration in sphinx-codelinks that goes with the ty move there.

[chrisjsewell]

Progress: the repository is now a uv workspace

Merged today: #1838 (a CI cell that builds the wheel, installs it into a throwaway
environment outside the project and builds a document with it — closes #1829) and #1839
(the move). master now looks like this:

sphinx-needs/
├── pyproject.toml           # workspace root: members, shared dependency groups, ruff/ty/pytest/poe config
├── uv.lock                  # one lock for the workspace
├── AGENTS.md  CLAUDE.md     # agent guidance (CLAUDE.md imports AGENTS.md and adds the cloud-session setup)
├── .github/  docker/  scripts/  .readthedocs.yml  .pre-commit-config.yaml
└── packages/
    └── sphinx-needs/        # the distribution: pyproject.toml, src/sphinx_needs/, tests/, docs/

Nothing about the published package changed (wheel verified file-for-file against 8.5.0's).
For contributors: uv sync then uv run poe <task> from the root; package tasks end in
-needs (test-needs, docs-needs, typecheck-needs). Open pull requests rebase with
git rebase -X find-renames=15% origin/master — the recipe, including the pyproject.toml
conflict, is in #1839's description. git log --follow recovers per-file history across
the move.

A first Claude Code cloud session was pointed at the branch cold and ran every task from
AGENTS.md alone (its report is on #1839); what it tripped over is now documented there.

Next: the Python floor moves to 3.11 across the suite (sphinx-needs up from 3.10, the
extensions down from 3.12), then the first import.

[chrisjsewell]

Progress: the release pipeline, and the first import

Merged since the last update, all on master:

• The Python floor is 3.11 across the suite (⬆️ Raise the Python floor to 3.11, and pin the workspace interpreter #1844), and the root .python-version pins the default environment to 3.13, so a bare uv sync gives every machine the same sphinx as CI's newest cell.
• One release workflow for every member (🔧 One tag-driven release workflow for every workspace member, on trusted publishing #1846, closes Switch PyPI publishing to Trusted Publishing (OIDC) #1758 and Update to flit 4 / flit_core 4 #1759). A tag <dist>-v<version> starts release.yaml, which validates the tag against the member's manifest, builds the wheel and sdist, resolves the wheel against PyPI alone, runs the member's suite against its dependencies as published, publishes with PyPI trusted publishing (no API token in the repository; one GitHub environment per package, pypi-<dist>, bound to that package's tag pattern) and creates the GitHub Release. For sphinx-needs it then pushes the bare <version> tag, so Read the Docs' stable, git+…@<version> pins and every existing link keep working. Historical tags are never renamed. The repository's own tooling moved into a virtual workspace member, tools/, and its "the manifests agree" fence runs in Lint.
• A release planner and a fast import check (🔧 Add a release planner and a fast import check, so the release order is known before the tag #1848). uv run poe release-plan prints, per publishable member, the last tag, what PyPI has, the shipped-code commits since, which gate would stop each dependant, and the order to release in. import_check.py builds a member's wheel, installs it into a throwaway environment outside the project and imports every module of it, so a symbol missing against the published sibling is named in seconds rather than at the end of a compatibility cell. Follow-ups are collected in 🔧 Release pipeline follow-ups: attestations, API-diff advice, poe bump, sdist build check, release train #1849.
• sphinx-mounts is imported, with its history (🔧 Import sphinx-mounts into the workspace as packages/sphinx-mounts #1850). git filter-repo moved every historical commit under packages/sphinx-mounts/, prefixed its tags sphinx-mounts-v* and rewrote #NN in its commit messages to useblocks/sphinx-mounts#NN; the result landed as a merge commit rather than a squash, so the history is reachable from master, and because the paths were rewritten git log packages/sphinx-mounts/… shows all of it without --follow. The old-to-new hash map is packages/sphinx-mounts/design/import-commit-map.txt. The root gained test-mounts, docs-mounts and build-mounts; typecheck covers both packages; CI runs a second matrix (the Mounts … jobs) plus a Bazel lane; the seven open issues moved here as Bazel: path confinement false positive for sandboxed external repositories #1852 to Feature: allow explicitly declared external dependencies in path_check #1858. The mounts documentation becomes a second Read the Docs project on this repository, pointed at packages/sphinx-mounts/.readthedocs.yaml; the domain moves and the old repository is archived once that is serving.

What the first import taught. The shared dependency groups, the one ruff/ty/pytest configuration and the one lock worked as designed, and the workspace fence now also refuses per-member [tool.ruff], [tool.pytest], [tool.ty] and [dependency-groups] tables, because a member [tool.ruff] silently replaces the root ruleset rather than extending it. Two tests/ packages cannot share pytest's rootdir, so a bare pytest at the root collects sphinx-needs and the tooling, each package's suite runs through its poe task, and a Lint step guards the root invocation. Two things want a repository-level answer before a third package joins: a reusable CI workflow keyed on the package, so the sphinx matrix is declared once, and a home for shared test tools (mounts currently reaches sphinx-needs' vendored PlantUML jar through PLANTUML_JAR).

Next: those two items, then sphinx-codelinks: its preparatory PRs first (Python floor to 3.11, conf.py beside the docs sources since Read the Docs runs without -c, its GitHub Pages site to Read the Docs, the ty port), then the import, then sphinx-test-reports.

[chrisjsewell]

Progress: sphinx-codelinks is in, and the workspace has one PlantUML

Merged since the last update, all on master:

• sphinx-codelinks is the third package (🔧 Import sphinx-codelinks into the workspace as packages/sphinx-codelinks #1871, a merge commit). Its whole history came across through git filter-repo, so every file has always lived at packages/sphinx-codelinks/ from this repository's point of view, and its seven release tags are here as sphinx-codelinks-v*. The wiring follows the sphinx-mounts precedent: root-owned lint, typing and pytest configuration, the shared dependency groups, one uv.lock. libclang is a root group used only where the codelinks suite runs, and the CI cell that installs it asserts the engine imports rather than letting 56 tests skip. Two things the old repository's CI shape could not see were fixed on the way: __version__ said 0.1.0 (now 1.4.0), and get_current_rev returned nothing in a git worktree or with packed refs. The docs are at https://sphinx-codelinks.readthedocs.io. The open issues have been transferred, the open pull requests carry a note pointing at the move recipe in 🔧 Import sphinx-codelinks into the workspace as packages/sphinx-codelinks #1871's description, and the old repository will be archived once the docs redirect is in place. Its history stays online: published git pins point at it.
• Extensions share one CI job (test-extensions.yaml): sphinx-mounts and sphinx-codelinks run together on Sphinx 7, 8 and 9 (Ubuntu) and Sphinx 9 (Windows), through a composite action that holds the renderer installs and the cell sync.
• One pinned PlantUML for every package (🔧 One pinned PlantUML for the whole workspace, vendored at vendor/plantuml/ #1870): a single jar under vendor/plantuml/, named by pin.toml with its checksum, committed in git, and verified against the pin by uv run poe verify-plantuml in Lint. The two jars the packages used to carry, at two versions four years old, are gone, and the sphinx-needs sdist is 71 % smaller because a repository-root directory cannot enter it. A fetched-on-demand design was built and reviewed first and dropped: it would have made rendering depend on reaching GitHub's release storage from every CI job, every Read the Docs build, offline machines and sandboxed agent sessions.
• The reusable test unit (🔧 One reusable test unit for every package's pytest cell #1864): one workflow_call workflow runs any package's suite in any matrix cell, so a new package adds a caller rather than a copy.
• uv run poe bump <dist> --bump minor (🔧 One command for the mechanical half of a release pull request, and two release-pipeline follow-ups #1869) does the mechanical half of a release pull request: version, the __version__ literal, dependants' floors, the lock, the changelog heading. It computes every edit before writing any, and refuses on a dirty guarded file.
• The README says why this is one repository and still several packages (📚 Say in the README why this is one repository but still several packages #1867), for the next time the question comes up.

Next: sphinx-test-reports (the last of the three), then the first releases from the workspace: sphinx-mounts 0.3.0 independently, sphinx-needs 9.0.0 (the 3.11 floor is the breaking change), and sphinx-codelinks after it with its floor moved to >=9,<10 by the bump tool.