OperonDBS 0.8.2__tar.gz → 0.8.3__tar.gz

{operondbs-0.8.2 → operondbs-0.8.3}/.github/workflows/publish.yml

@@ -43,7 +43,9 @@ jobs:
           python-version: "3.12"
       - run: python -m pip install --upgrade pip
       - run: python -m pip install -e '.[docs]'
-      - run: sphinx-build -W --keep-going -b html docs docs/_build/html
+      - run: |
+          sphinx-build -W --keep-going -b html docs/en docs/_build/en/html
+          sphinx-build -W --keep-going -b html docs/zh docs/_build/zh/html
 
   wheels:
     strategy:

{operondbs-0.8.2 → operondbs-0.8.3}/.github/workflows/test.yml

@@ -25,7 +25,9 @@ jobs:
           cache-dependency-path: pyproject.toml
       - run: python -m pip install --upgrade pip
       - run: python -m pip install -e '.[docs]'
-      - run: sphinx-build -W --keep-going -b html docs docs/_build/html
+      - run: |
+          sphinx-build -W --keep-going -b html docs/en docs/_build/en/html
+          sphinx-build -W --keep-going -b html docs/zh docs/_build/zh/html
 
   pytest:
     strategy:

{operondbs-0.8.2 → operondbs-0.8.3}/.gitignore

@@ -29,6 +29,6 @@ htmlcov/
 /site/
 /docs/_build/
 /workflows/
-/HPC/
+/others/
 .matrix/
 cobertura.xml

{operondbs-0.8.2 → operondbs-0.8.3}/AGENTS.md

@@ -26,7 +26,7 @@ principle-to-implementation mapping.
 
 Current version markers (must stay consistent across code and docs):
 
-- `operon` 0.8.2 (`pyproject.toml`)
+- `operon` 0.8.3 (`pyproject.toml`)
 - database schema 2.11 (`operon/database.py`, `SCHEMA_VERSION`)
 - metadata schema 1.4 (`operon/schema.py`, `METADATA_SCHEMA_VERSION`)
 
@@ -83,17 +83,48 @@ The project is licensed AGPL-3.0-or-later (`LICENSE` at the repo root).
     Confirm → background worker → notify + reload or inline error. Phase 3
     actions in the same module: `import_dataset` (commits wizard drafts
     through the shared single-transaction `import_wizard._commit`),
-    `reserve_entity_ids`, `create_release`, `export`, and `run_coverage`
+    `reserve_entity_ids`, `create_release`, `export`, `run_coverage`
     (a below-threshold coverage report returns `exit_code=1` in the result
-    dict — a warning, not an exception). The
+    dict — a warning, not an exception), `preflight_backend`, `run_analysis`
+    (backing the AnalyzeModal launched from the Config screen's Run analysis
+    button or the Tasks screen's New analysis button; the modal mirrors
+    `--backend` — project default / local / slurm / ssh — and preflights the
+    selection inline, and cancellation sets the core's cooperative
+    `cancel_event`, so a queued Slurm job or array is cancelled with one
+    `scancel`), `run_external` (backing the Tasks screen's Run external
+    dialog, which mirrors `run-external` field by field and opens the run
+    record when it finishes) and `write_analysis_report` (backing the
+    Analysis hits browser's Export button: it runs the same read-only query
+    and the same renderer as `report analysis --hits --format … --out …`, so
+    the file is byte-identical and, like that command, writes no provenance
+    rows). Phase 3 also covers the
+    derived-artifact loop: `run_classify` (the Config screen's Run classify
+    dialog, mirroring `classify-sequences` with the CLI's summary and a re-run
+    button), and — on the Files screen — `extract_domains`, `select_sequences`,
+    `adopt` and `fanout` (modals in `operon/tui/screens/derived_ops.py`:
+    extract/select chain into the adopt dialog with `derived_from` prefilled and
+    leave their output unregistered, adopt's manifest mode previews before
+    Confirm, and fanout's dry run is a mandatory preflight). Read-only TUI views added for `report analysis --hits` (alignment
+    hits with the CLI's filters and columns) and for `sequence_labels` (the
+    classify-sequences output: a per-file section in the Files detail plus
+    the project-wide label summary behind the Files screen's `l` binding), which
+    has no CLI reader at all. The
     Config screen (`operon/tui/screens/config.py`, nav key `6`) edits
-    `config/profiles/*.yaml` (kind `qc`) and single recipes inside
+    `config/profiles/*.yaml` (kind `qc` and kind `sequence_classification` —
+    each kind has its own form, dispatched by the document's own kind, with the
+    classification widgets in `operon/tui/screens/config_classification.py`
+    and `actions.save_classification_profile` sharing `save_profile`'s version,
+    snapshot and rollback machinery; a profile whose conditions nest deeper
+    than one `any:`/`not:` level opens read-only) and single recipes inside
     `config/tools.yaml` through structured control-based forms (no free-text
     YAML): every save bumps the `version`, records the same content-addressed
     snapshot the CLI records (`qc_profiles` / `recipe_snapshots`), and
     restores the previous file bytes on failure; keys the forms do not model
     are preserved verbatim; history modals restore snapshots into the editor
     as the next version; tools-check runs in a worker with per-row updates.
+    `operon/tui/parity.py` is the CLI/TUI parity registry: every CLI leaf
+    command is registered `implemented`/`cli-only`/`planned`, enforced by
+    `tests/unit/test_tui_cli_parity.py` (see Conventions).
     Textual is imported only inside this package, which the `tui` command
     handler imports lazily.
   - Other top-level modules by responsibility: `database.py` (SQLite schema
@@ -127,8 +158,16 @@ The project is licensed AGPL-3.0-or-later (`LICENSE` at the repo root).
 - `docs/` — Sphinx documentation in two mirrored language trees, `docs/en/`
   and `docs/zh/`, each split into `overview.md`, `getting-started/`,
   `guides/`, `architecture/`, `reference/`, `operations/`, and
-  `contributor/`. Built with `docs/conf.py`; published via Read the Docs
-  (`.readthedocs.yaml`).
+  `contributor/`. Each tree is a Sphinx project of its own
+  (`docs/<language>/conf.py`, sharing settings from `docs/conf_common.py`) and
+  a Read the Docs project of its own, linked there as parent and translation:
+  `operonproject` (English) and `operonproject-zh` (Chinese). Read the Docs
+  accepts no build-configuration file name other than `.readthedocs.yaml`, so
+  each tree carries one next to its `conf.py`
+  (`docs/<language>/.readthedocs.yaml`) and the dashboard points the project at
+  that path. `docs/locales/` is the catalog directory
+  for a future gettext-maintained language; `tests/unit/test_docs_projects.py`
+  guards the layout.
 - `benchmarks/` — representative entity sets for QC performance diagnostics
   (see `docs/*/operations/qc-performance.md`).
 - `scripts/` — local developer tooling; `setup-test-matrix.sh` and
@@ -158,7 +197,8 @@ scripts/run-test-matrix.sh          # whole suite on 3.10-3.15 concurrently
 
 python setup.py build_ext --inplace # rebuild only the Cython extension
 
-sphinx-build -W --keep-going -b html docs docs/_build/html  # strict docs build
+sphinx-build -W --keep-going -b html docs/en docs/_build/en/html  # strict build,
+sphinx-build -W --keep-going -b html docs/zh docs/_build/zh/html  # one per language
 ```
 
 Run the relevant test category after any change; run the full suite before
@@ -216,15 +256,18 @@ proceed with caution).
   bytes must raise `ConflictError`; identical bytes must be idempotent.
 - Manual overrides (e.g. `curate`, forced `set-state`) must always be
   recorded in the `changes` audit table.
+- CLI-first: new capabilities land in the CLI/core first, and the TUI never
+  runs ahead of the CLI. Any change to CLI commands, flags, or the TUI
+  surface must update the parity registry `operon/tui/parity.py` in the same
+  commit — the parity tests in `tests/unit/test_tui_cli_parity.py` fail
+  otherwise. Commands intentionally not offered in the TUI are registered
+  `cli-only` with a reason; known gaps are registered `planned` with a
+  milestone.
 - `docs/*/operations/database-compatibility.md` lists migration code that
   exists only for pre-1.0 databases and is scheduled for removal at the 1.0
   release; check it before touching `operon/database.py` migrations or the
   NCBI adapter's schema-upgrade path.
-- The `operon.qc` module uses CFFI (specifically, Cython), so static analysis
-  tools, such as `flake8`, will report "undefined reference" errors (F821).
-  Using `# noqa: F821` behind the line **ONLY** when importing `operon.qc`
-  and an F821 error is likely to occur. Globally ignoring F821 is **STRICKLY
-  PROHIBITED**.
+- Using `ruff` to re-format the code.
 
 ## Defect reports
 
@@ -256,12 +299,15 @@ change:
   `docs/*/operations/`
 - Contributor-facing processes → `docs/*/contributor/`; navigation →
   `docs/*/index.md`
+- The set of language projects → `docs/<language>/conf.py`, its
+  `docs/<language>/.readthedocs.yaml`, and the registry in
+  `tests/unit/test_docs_projects.py`
 
-Version markers in docs (`operon` 0.8.2, database schema 2.11, metadata
+Version markers in docs (`operon` 0.8.3, database schema 2.11, metadata
 schema 1.4) must match `pyproject.toml` and the code. Do not write the
 current values literally in Markdown sources: use the `myst_substitutions`
 references `{{ operon_version }}`, `{{ db_schema }}`, and
-`{{ metadata_schema }}`, which `docs/conf.py` resolves from the single
+`{{ metadata_schema }}`, which `docs/conf_common.py` resolves from the single
 sources above at build time. Substitutions expand in paragraph text only,
 never inside code spans or fenced code blocks — examples there use
 `<version>` placeholders instead. Intentional historical pins stay literal — either on the

{operondbs-0.8.2 → operondbs-0.8.3}/MANIFEST.in

@@ -4,12 +4,13 @@ include LICENSE
 include MANIFEST.in
 include README.md
 include README_ZH.md
-include .readthedocs.yaml
+include docs/en/.readthedocs.yaml
+include docs/zh/.readthedocs.yaml
 include pyproject.toml
 include setup.py
 recursive-include .github *.yml
 recursive-include benchmarks *.tsv
-recursive-include docs *.css *.html *.js *.md *.py *.txt
+recursive-include docs *.css *.html *.js *.md *.po *.py *.txt
 prune docs/_build
 recursive-include operon *.py *.pyx *.tcss
 recursive-include operon/tui/assets *.png *.z *.md

{operondbs-0.8.2 → operondbs-0.8.3}/OperonDBS.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OperonDBS
-Version: 0.8.2
+Version: 0.8.3
 Summary: Operon the Database System: Archive, Quality-Control, Organize, Analyze and Release Your Bio-Data
 Author-email: hyli360 <lihuanyu2003@gmail.com>
 License-Expression: AGPL-3.0-or-later
@@ -93,11 +93,12 @@ python -m pip install -e '.[dev]'
 
 ## Documentation
 
-The complete documentation is maintained in [English](docs/en/index.md) and [Chinese](docs/zh/index.md). To build the Sphinx site locally:
+The complete documentation is maintained in [English](docs/en/index.md) and [Chinese](docs/zh/index.md). Each language is its own Sphinx project; build both without warnings:
 
 ```bash
 python -m pip install -e '.[docs]'
-sphinx-build -W --keep-going -b html docs docs/_build/html
+sphinx-build -W --keep-going -b html docs/en docs/_build/en/html
+sphinx-build -W --keep-going -b html docs/zh docs/_build/zh/html
 ```
 
-Read the Docs uses the repository's `.readthedocs.yaml` configuration and publishes a language-selection page with mirrored `/en/` and `/zh/` documentation trees.
+Read the Docs publishes two projects linked as parent and translation: `operonproject` (English, `https://operonproject.readthedocs.io/en/latest/`) and `operonproject-zh` (Chinese, `https://operonproject.readthedocs.io/zh-cn/latest/`), each built from its own `docs/<language>/.readthedocs.yaml`.

{operondbs-0.8.2 → operondbs-0.8.3}/OperonDBS.egg-info/SOURCES.txt

@@ -1,5 +1,4 @@
 .gitignore
-.readthedocs.yaml
 AGENTS.md
 LICENSE
 MANIFEST.in
@@ -16,12 +15,10 @@ OperonDBS.egg-info/entry_points.txt
 OperonDBS.egg-info/requires.txt
 OperonDBS.egg-info/top_level.txt
 benchmarks/qc_representative_entities.tsv
-docs/conf.py
-docs/index.md
+docs/conf_common.py
 docs/requirements.txt
-docs/_static/language-switcher.js
-docs/_static/operon.css
-docs/_templates/layout.html
+docs/en/.readthedocs.yaml
+docs/en/conf.py
 docs/en/index.md
 docs/en/overview.md
 docs/en/architecture/extensibility.md
@@ -77,6 +74,9 @@ docs/en/reference/recipe-fields.md
 docs/en/reference/recipe-overview.md
 docs/en/reference/recipe-parsers-examples.md
 docs/en/reference/resolved-issues.md
+docs/locales/README.md
+docs/zh/.readthedocs.yaml
+docs/zh/conf.py
 docs/zh/index.md
 docs/zh/overview.md
 docs/zh/architecture/extensibility.md
@@ -183,21 +183,30 @@ operon/tui/actions.py
 operon/tui/app.py
 operon/tui/app.tcss
 operon/tui/data.py
+operon/tui/parity.py
 operon/tui/splash.py
 operon/tui/splash_terminal.py
 operon/tui/assets/splash.png
 operon/tui/assets/splash.rgb.z
 operon/tui/screens/__init__.py
+operon/tui/screens/analyze.py
+operon/tui/screens/classify.py
 operon/tui/screens/common.py
 operon/tui/screens/config.py
+operon/tui/screens/config_classification.py
 operon/tui/screens/coverage.py
 operon/tui/screens/decisions.py
+operon/tui/screens/derived_ops.py
 operon/tui/screens/entities.py
+operon/tui/screens/environments.py
 operon/tui/screens/files.py
 operon/tui/screens/files_ops.py
+operon/tui/screens/hits.py
 operon/tui/screens/home.py
 operon/tui/screens/import_wizard.py
+operon/tui/screens/labels.py
 operon/tui/screens/publish.py
+operon/tui/screens/run_external.py
 operon/tui/screens/runs.py
 tests/__init__.py
 tests/helpers.py
@@ -233,6 +242,7 @@ tests/unit/test_coverage_edges.py
 tests/unit/test_database_edges_more.py
 tests/unit/test_defect_registry.py
 tests/unit/test_defects_cli.py
+tests/unit/test_docs_projects.py
 tests/unit/test_docs_versions.py
 tests/unit/test_environment.py
 tests/unit/test_environment_capture.py
@@ -276,8 +286,12 @@ tests/unit/test_timetree_snapshots.py
 tests/unit/test_tools_edges.py
 tests/unit/test_tools_execution_more.py
 tests/unit/test_tui.py
+tests/unit/test_tui_analyze.py
+tests/unit/test_tui_cli_parity.py
 tests/unit/test_tui_config.py
+tests/unit/test_tui_derived_ops.py
 tests/unit/test_tui_flows_more.py
+tests/unit/test_tui_m3_loop.py
 tests/unit/test_tui_publish.py
 tests/unit/test_tui_screens_more.py
 tests/unit/test_tui_splash_terminal.py

{operondbs-0.8.2 → operondbs-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OperonDBS
-Version: 0.8.2
+Version: 0.8.3
 Summary: Operon the Database System: Archive, Quality-Control, Organize, Analyze and Release Your Bio-Data
 Author-email: hyli360 <lihuanyu2003@gmail.com>
 License-Expression: AGPL-3.0-or-later
@@ -93,11 +93,12 @@ python -m pip install -e '.[dev]'
 
 ## Documentation
 
-The complete documentation is maintained in [English](docs/en/index.md) and [Chinese](docs/zh/index.md). To build the Sphinx site locally:
+The complete documentation is maintained in [English](docs/en/index.md) and [Chinese](docs/zh/index.md). Each language is its own Sphinx project; build both without warnings:
 
 ```bash
 python -m pip install -e '.[docs]'
-sphinx-build -W --keep-going -b html docs docs/_build/html
+sphinx-build -W --keep-going -b html docs/en docs/_build/en/html
+sphinx-build -W --keep-going -b html docs/zh docs/_build/zh/html
 ```
 
-Read the Docs uses the repository's `.readthedocs.yaml` configuration and publishes a language-selection page with mirrored `/en/` and `/zh/` documentation trees.
+Read the Docs publishes two projects linked as parent and translation: `operonproject` (English, `https://operonproject.readthedocs.io/en/latest/`) and `operonproject-zh` (Chinese, `https://operonproject.readthedocs.io/zh-cn/latest/`), each built from its own `docs/<language>/.readthedocs.yaml`.

{operondbs-0.8.2 → operondbs-0.8.3}/README.md

@@ -45,11 +45,12 @@ python -m pip install -e '.[dev]'
 
 ## Documentation
 
-The complete documentation is maintained in [English](docs/en/index.md) and [Chinese](docs/zh/index.md). To build the Sphinx site locally:
+The complete documentation is maintained in [English](docs/en/index.md) and [Chinese](docs/zh/index.md). Each language is its own Sphinx project; build both without warnings:
 
 ```bash
 python -m pip install -e '.[docs]'
-sphinx-build -W --keep-going -b html docs docs/_build/html
+sphinx-build -W --keep-going -b html docs/en docs/_build/en/html
+sphinx-build -W --keep-going -b html docs/zh docs/_build/zh/html
 ```
 
-Read the Docs uses the repository's `.readthedocs.yaml` configuration and publishes a language-selection page with mirrored `/en/` and `/zh/` documentation trees.
+Read the Docs publishes two projects linked as parent and translation: `operonproject` (English, `https://operonproject.readthedocs.io/en/latest/`) and `operonproject-zh` (Chinese, `https://operonproject.readthedocs.io/zh-cn/latest/`), each built from its own `docs/<language>/.readthedocs.yaml`.

{operondbs-0.8.2 → operondbs-0.8.3}/README_ZH.md

@@ -43,11 +43,12 @@ python -m pip install -e '.[dev]'
 
 ## 文档
 
-完整文档同时维护[中文](docs/zh/index.md)和[英文](docs/en/index.md)版本。本地构建 Sphinx 站点：
+完整文档同时维护[中文](docs/zh/index.md)和[英文](docs/en/index.md)版本。每种语言是独立的 Sphinx 工程，两条构建都必须无警告通过：
 
 ```bash
 python -m pip install -e '.[docs]'
-sphinx-build -W --keep-going -b html docs docs/_build/html
+sphinx-build -W --keep-going -b html docs/en docs/_build/en/html
+sphinx-build -W --keep-going -b html docs/zh docs/_build/zh/html
 ```
 
-Read the Docs 使用仓库根目录的 `.readthedocs.yaml`，发布带语言选择入口及 `/zh/`、`/en/` 镜像目录的文档站点。
+Read the Docs 发布两个互为父项目与翻译的项目：`operonproject`（英文，`https://operonproject.readthedocs.io/en/latest/`）与 `operonproject-zh`（中文，`https://operonproject.readthedocs.io/zh-cn/latest/`），各自从 `docs/<语言>/.readthedocs.yaml` 构建。

operondbs-0.8.3/docs/conf_common.py

@@ -0,0 +1,218 @@
+"""Shared Sphinx configuration for the per-language Operon documentation.
+
+The documentation is one Sphinx project per language and one Read the Docs
+project per language:
+
+===============  ====================  ===============================
+Source tree      Sphinx configuration  Read the Docs project
+===============  ====================  ===============================
+``docs/en/``     ``docs/en/conf.py``   ``docs/en/operonproject`` (parent)
+``docs/zh/``     ``docs/zh/conf.py``   ``docs/zh/operonproject-zh``
+===============  ====================  ===============================
+
+Read the Docs links the two projects as parent and translation; that link is
+dashboard state (Admin -> Settings -> Translations), not repository state.
+Each project also names the build configuration file it uses in its
+``Build configuration file`` setting, and Read the Docs accepts no file name
+there other than ``.readthedocs.yaml``: the language is identified by the
+directory holding it, so the repository ships ``docs/en/.readthedocs.yaml`` and
+``docs/zh/.readthedocs.yaml``.
+
+Read the Docs runs Sphinx from the directory that holds the configuration
+file. That directory is the source directory — every page of a language lives
+next to its own ``conf.py`` — and Read the Docs always passes
+``-D language=<dashboard language>``, which overrides ``language`` here. The
+dashboard is therefore authoritative for the published site, and a project
+whose dashboard language contradicts its configuration fails the build (see
+``_check_declared_language``) instead of silently publishing the wrong
+language.
+
+Everything the language projects share — version markers, MyST settings,
+theme options, the gettext entry points — lives in this module; each
+``conf.py`` only declares its own language and title.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _distribution_version
+from pathlib import Path
+
+from sphinx.errors import ConfigError
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as tomllib
+
+
+DOCS_DIR = Path(__file__).resolve().parent
+REPO_ROOT = DOCS_DIR.parent
+
+#: gettext catalogs, one ``.po`` per document, under
+#: ``docs/locales/<language>/LC_MESSAGES/<docname>.po``. The directory is
+#: optional: only a project that localizes through gettext registers it, so a
+#: Markdown-only checkout never gets a missing-locale warning. See
+#: ``docs/locales/README.md``.
+LOCALES_DIR = DOCS_DIR / "locales"
+
+#: Declare this as a project's ``language`` when the build decides instead of
+#: the configuration — the case for a project that reuses another tree's
+#: sources with gettext catalogs and takes its language from Read the Docs'
+#: ``-D language=``.
+LANGUAGE_FROM_BUILD = "auto"
+
+#: ``(language, Read the Docs project)`` pairs declared by the ``conf.py``
+#: files loaded in this Sphinx process.
+_DECLARED_PROJECTS: list[tuple[str, str]] = []
+
+
+def normalize_language(code: str) -> str:
+    """Return *code* in Sphinx's spelling, from any usual spelling.
+
+    Read the Docs stores and publishes lowercase-dashed codes (``zh-cn``),
+    while Sphinx wants ``ll_CC`` (``zh_CN``); ``en`` is the same in both.
+    """
+
+    primary, _, region = code.strip().lower().replace("-", "_").partition("_")
+    return f"{primary}_{region.upper()}" if region else primary
+
+
+def package_version() -> str:
+    """Return the released ``operon`` version."""
+
+    try:
+        return _distribution_version("OperonDBS")
+    except PackageNotFoundError:
+        with (REPO_ROOT / "pyproject.toml").open("rb") as handle:
+            return tomllib.load(handle)["project"]["version"]
+
+
+def source_constant(module: str, name: str) -> str:
+    """Read a module-level string constant, falling back to the source file."""
+
+    try:
+        imported = __import__(f"operon.{module}", fromlist=[name])
+        return str(getattr(imported, name))
+    except Exception:
+        source = (REPO_ROOT / "operon" / f"{module}.py").read_text(encoding="utf-8")
+        match = re.search(rf'^{name} = "([^"]+)"', source, re.MULTILINE)
+        if match is None:
+            raise RuntimeError(f"cannot resolve {name} from operon/{module}.py")
+        return match.group(1)
+
+
+def apply_shared_settings(
+    namespace: dict,
+    *,
+    language: str,
+    title_suffix: str,
+    rtd_project: str,
+) -> None:
+    """Fill *namespace* (a ``conf.py``'s globals) with the shared settings.
+
+    ``language`` is the language this tree is written in, ``title_suffix``
+    completes the HTML title (``documentation`` / ``文档``), and
+    ``rtd_project`` names the Read the Docs project so that the language guard
+    can point at the right dashboard page.
+    """
+
+    release = package_version()
+    author = "Project Operon Development Group"
+
+    namespace.update(
+        # `conf.py` is an extension: Sphinx picks `setup` out of its namespace
+        # and runs it before `config-inited`, which is where the language guard
+        # hangs off. Registering it here keeps the language `conf.py` files
+        # free of boilerplate.
+        setup=setup,
+        release=release,
+        version=release,
+        project="Operon",
+        author=author,
+        copyright=f"2026, {author}. All Rights Reserved",
+        language=language,
+        # Markdown sources reference these as {{ operon_version }} /
+        # {{ db_schema }} / {{ metadata_schema }} in paragraph text.
+        # Substitutions do not expand inside code spans or fenced code blocks,
+        # so examples there use `<version>` placeholders instead. Historical
+        # version mentions stay literal and are guarded by
+        # tests/unit/test_docs_versions.py.
+        myst_substitutions={
+            "operon_version": release,
+            "db_schema": source_constant("database", "SCHEMA_VERSION"),
+            "metadata_schema": source_constant("schema", "METADATA_SCHEMA_VERSION"),
+        },
+        extensions=["myst_parser"],
+        source_suffix={".md": "markdown"},
+        root_doc="index",
+        exclude_patterns=["_build", "Thumbs.db", ".DS_Store"],
+        nitpicky=True,
+        suppress_warnings=["myst.header"],
+        myst_heading_anchors=4,
+        myst_enable_extensions=[
+            "colon_fence",
+            "deflist",
+            "fieldlist",
+            "substitution",
+        ],
+        # One catalog per document, so that the catalogs of a future gettext
+        # project mirror the page names of this tree.
+        gettext_compact=False,
+        html_theme="sphinx_rtd_theme",
+        html_title=f"Operon {release} {title_suffix}",
+        # The version and language selectors are rendered by the theme on Read
+        # the Docs and filled in by the Read the Docs Addons flyout: the
+        # language selector appears once the translation project is linked to
+        # this one in the dashboard.
+        html_theme_options={
+            "collapse_navigation": False,
+            "navigation_depth": 4,
+            "sticky_navigation": True,
+            "titles_only": True,
+            "version_selector": True,
+            "language_selector": True,
+        },
+    )
+
+    if LOCALES_DIR.is_dir():
+        namespace["locale_dirs"] = [str(LOCALES_DIR)]
+
+    _DECLARED_PROJECTS.append((language, rtd_project))
+
+
+def _check_declared_language(app, config) -> None:
+    """Refuse to build a language the configuration does not declare.
+
+    Read the Docs overrides ``language`` with the language of the project, so a
+    mismatch means the two settings disagree about what is being published.
+    Failing here — with the dashboard page named — is the difference between a
+    loud build error and a Chinese project that quietly serves English pages.
+    """
+
+    built = normalize_language(config.language)
+    mismatched = [
+        (declared, project)
+        for declared, project in _DECLARED_PROJECTS
+        if declared != LANGUAGE_FROM_BUILD and normalize_language(declared) != built
+    ]
+    if not mismatched:
+        return
+
+    declared, project = mismatched[0]
+    raise ConfigError(
+        f"the {project!r} project is configured to build language {built!r} "
+        "(Read the Docs passes the language of a project as `-D language=...`, "
+        "which wins over everything set here) while this configuration declares "
+        f"{declared!r}. Set the language of {project!r} in Admin -> Settings to "
+        "the language of this tree, or point the project at the configuration "
+        "file of the tree it should build. A project that is meant to build a "
+        "language it does not declare (for example one driven by gettext "
+        f"catalogs) declares language = {LANGUAGE_FROM_BUILD!r} instead."
+    )
+
+
+def setup(app):
+    app.connect("config-inited", _check_declared_language)
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

operondbs-0.8.3/docs/en/.readthedocs.yaml

@@ -0,0 +1,29 @@
+# Read the Docs build configuration for the parent documentation project
+# (`operonproject`), which publishes the English tree at
+# https://operonproject.readthedocs.io/en/latest/ .
+#
+# Read the Docs accepts no build-configuration file name other than
+# `.readthedocs.yaml`, so each language keeps one next to its `conf.py` and its
+# project names that path in Admin -> Settings -> `Build configuration file`:
+# `docs/en/.readthedocs.yaml` for this project, `docs/zh/.readthedocs.yaml` for
+# the Chinese translation project (`operonproject-zh`), which is linked to this
+# project on its Translations page and then served under this project's domain
+# with the language prefix. See docs/en/contributor/documentation-deployment.md.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  # Read the Docs runs Sphinx from the directory holding this file, so
+  # `docs/en/` is both the configuration directory and the source directory.
+  # Paths elsewhere in this file stay relative to the repository root.
+  configuration: docs/en/conf.py
+  builder: html
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

operondbs-0.8.3/docs/en/conf.py

@@ -0,0 +1,24 @@
+"""Sphinx configuration for the English Operon documentation.
+
+This tree is the parent Read the Docs project ``operonproject``, published at
+``https://operonproject.readthedocs.io/en/latest/``; the Chinese translation
+project builds ``docs/zh/`` from ``docs/zh/.readthedocs.yaml``. Shared settings
+live in ``docs/conf_common.py``; see
+``contributor/documentation-deployment.md``.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from conf_common import apply_shared_settings  # noqa: E402
+
+apply_shared_settings(
+    globals(),
+    language="en",
+    title_suffix="documentation",
+    rtd_project="operonproject",
+)