[pull] master from useblocks:master

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -18,6 +18,7 @@ body:
         - sphinx-needs
         - sphinx-mounts
         - sphinx-codelinks
+        - sphinx-test-reports
         - the repository (workflows, CI, release, docker, tooling)
     validations:
       required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -13,6 +13,7 @@ body:
         - sphinx-needs
         - sphinx-mounts
         - sphinx-codelinks
+        - sphinx-test-reports
         - the repository (workflows, CI, release, docker, tooling)
     validations:
       required: true

.github/dependabot.yml

@@ -57,6 +57,11 @@ updates:
       # (`sphinx-needs>=8.5.0,<9`), and that specifier is a floor moved by hand at release
       # time by `propagate_floors.py`, not by dependabot
       - dependency-name: sphinx-codelinks
+      # the fourth member, same reason: `sphinx-test-reports` is a real PyPI project as
+      # well as a directory under `packages/`, and it names the published sphinx-needs by
+      # name in two extras (`sphinx-needs>=8.5.0,<9`) -- a floor `propagate_floors.py`
+      # moves at release time, not dependabot
+      - dependency-name: sphinx-test-reports
       # the workspace root itself. Its name is not on PyPI at all, so there is nothing to
       # bump to -- this pre-empts the same #14004 noise rather than fixing a live proposal
       - dependency-name: sphinx-needs-workspace

.github/issue-labeler.yml

@@ -7,14 +7,16 @@
 # patterns case-insensitive, like the workflow's `contains()` gate, so the two agree.
 'pkg: sphinx-needs':
   - '/### Package[^#]*\bsphinx-needs\b/i'
-# `sphinx-mounts` contains neither `sphinx-needs` nor `sphinx-codelinks` as a
-# \b-delimited word, and neither of those contains the others, so no two patterns can
-# match one choice. Every pattern has to be present before its option is offered by a
-# form, though: the workflow runs with `sync-labels: 1`, so a pattern that is missing when
-# its option is picked means the label is synced away rather than merely not added
+# No two of `sphinx-needs`, `sphinx-mounts`, `sphinx-codelinks` and `sphinx-test-reports`
+# contains another as a \b-delimited word, so no two patterns can match one choice. Every
+# pattern has to be present before its option is offered by a form, though: the workflow
+# runs with `sync-labels: 1`, so a pattern that is missing when its option is picked means
+# the label is synced away rather than merely not added
 'pkg: sphinx-mounts':
   - '/### Package[^#]*\bsphinx-mounts\b/i'
 'pkg: sphinx-codelinks':
   - '/### Package[^#]*\bsphinx-codelinks\b/i'
+'pkg: sphinx-test-reports':
+  - '/### Package[^#]*\bsphinx-test-reports\b/i'
 'pkg: workspace':
   - '/### Package[^#]*\bthe repository\b/i'

.github/labeler.yml

@@ -15,6 +15,9 @@
 'pkg: sphinx-codelinks':
   - changed-files:
       - any-glob-to-any-file: 'packages/sphinx-codelinks/**'
+'pkg: sphinx-test-reports':
+  - changed-files:
+      - any-glob-to-any-file: 'packages/sphinx-test-reports/**'
 'pkg: sphinx-needs-testkit':
   - changed-files:
       - any-glob-to-any-file: 'packages/sphinx-needs-testkit/**'

.github/workflows/benchmark.yaml

@@ -9,7 +9,7 @@ jobs:
     runs-on: "ubuntu-latest"
     steps:
       - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           # 3.12+: on 3.11 the lock resolves sphinx 8.2, and this job wants the newest sphinx

.github/workflows/ci.yaml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           # the pinned interpreter (root `.python-version`) is not on the runner image, so
@@ -61,7 +61,7 @@ jobs:
         # ONE probe at a time, and one per package: with both planted at once a gate that had
         # dropped one package would still go red on the other and look healthy.
         run: |
-          probes="packages/sphinx-needs/src/sphinx_needs/_ty_gate_probe.py packages/sphinx-mounts/src/sphinx_mounts/_ty_gate_probe.py"
+          probes="packages/sphinx-needs/src/sphinx_needs/_ty_gate_probe.py packages/sphinx-mounts/src/sphinx_mounts/_ty_gate_probe.py packages/sphinx-codelinks/src/sphinx_codelinks/_ty_gate_probe.py packages/sphinx-test-reports/src/sphinxcontrib/test_reports/_ty_gate_probe.py"
           # shellcheck disable=SC2064
           trap "rm -f $probes" EXIT
           for probe in $probes; do
@@ -254,7 +254,7 @@ jobs:
             sphinx-group: "sphinx-9"
     steps:
       - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           cache-suffix: ${{ matrix.python-version }}-${{ matrix.sphinx-group }}
@@ -285,7 +285,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           # 3.12+: on 3.11 the lock resolves sphinx 8.2, and this job wants the newest sphinx
@@ -383,7 +383,7 @@ jobs:
         # history, so the default shallow checkout is enough -- but it does need `.git`,
         # so this job must not be given `fetch-depth: 0`-free surprises like a
         # `sparse-checkout` that omits it
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           cache-suffix: docs-codelinks
@@ -408,6 +408,116 @@ jobs:
         run: uv run --no-sync sphinx-build -nW --keep-going -b html docs docs/_build/html -T
         working-directory: packages/sphinx-codelinks
 
+  docs-reports:
+    name: Docs reports
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    # sphinx-test-reports' docs went from five warnings to zero in this pull request, and
+    # without this job nothing holds that: the Read the Docs build is not a required check,
+    # it is `-W` WITHOUT `-n`, and that project's settings do not point at this repository
+    # yet. `docs.yaml`'s linkcheck is scoped to sphinx-needs' own docs. sphinx-mounts has no
+    # docs job either, so this is a deliberate departure from that precedent rather than an
+    # oversight -- the difference is that these docs RENDER, which is a failure mode a build
+    # catches and a reviewer does not.
+    #
+    # No `paths:` filter and no `if:`: a change to `src/` with no change to `docs/` is
+    # precisely the change that breaks a docs build.
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+          cache-suffix: docs-reports
+          # no `python-version`, so this runs on the root `.python-version`
+          cache-python: true
+      - name: Install graphviz
+        # 13 `needflow` directives across three pages need `dot`; PlantUML needs a JDK,
+        # which every Linux runner image already has
+        run: sudo apt-get install graphviz
+      - name: Point PLANTUML_JAR at the vendored jar
+        # the one jar `vendor/plantuml/pin.toml` names, verified against the pin first.
+        # The capture shape is the workspace's ONE shape and is fenced as such by
+        # `tools/tests/test_ci_plantuml_steps.py`, on every site including ubuntu-only ones:
+        # `shell: bash` for pipefail, `tr -d` for Windows' carriage return, and the export on
+        # the very next line. Uniform so that a step copied anywhere is already right --
+        # vendor/plantuml/README.md, "The step CI runs", says why each clause matters.
+        shell: bash
+        run: |
+          jar="$(uv run --no-project python tools/src/sn_tools/fetch_plantuml.py --verify | tr -d '\r')"
+          echo "PLANTUML_JAR=$jar" >> "$GITHUB_ENV"
+      - name: Install the docs environment
+        # `docs.yaml`'s idiom -- sync ONE environment, then run the builder in it with
+        # `--no-sync` -- rather than `uv run --frozen poe docs-reports`, which pays for two
+        # environments because poe itself lives in the `dev` group. Keep in step with the
+        # `docs-reports` poe task.
+        run: uv sync --frozen --no-default-groups --extra docs-reports
+      - name: Build the docs
+        # `-nW --keep-going`, from the poe task: a nitpick warning is an error here, which
+        # is stricter than the Read the Docs build and is the point of the job
+        run: uv run --no-sync sphinx-build -nW --keep-going -b html docs docs/_build/html -T
+        working-directory: packages/sphinx-test-reports
+
+  toolchain-free:
+    name: Toolchain-free (sphinx-test-reports)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    # sphinx-test-reports' converter (`test-reports`) and its pytest plugin are meant to run
+    # where the documentation toolchain is NOT installed -- that is why Sphinx and
+    # sphinx-needs are an EXTRA of that package rather than dependencies. This job is the
+    # only thing that keeps it true: it installs the package with the dependencies it
+    # declares, asserts that sphinx, sphinx_needs and docutils are all absent, and runs the
+    # modules that do not need a build.
+    #
+    # It CANNOT be a matrix cell, and that is structural rather than a configuration gap:
+    # the root's `[project] dependencies` name every member, `[project] dependencies` are
+    # installed in every environment, and sphinx-needs declares sphinx at runtime -- so
+    # every environment a `uv sync` at this root can produce has Sphinx in it, whatever
+    # groups are asked for. The environment is therefore built OUTSIDE the project with
+    # `uv pip install --no-sources`, exactly as `release.yaml`'s compat cell builds its own.
+    #
+    # It replaces the `toolchain_free` session of the noxfile the import retired. That
+    # noxfile's other lane, `plugin_floor` (the plugin on the oldest pytest of each Python),
+    # is deliberately NOT here: it belongs with the release that makes the plugin a shipped
+    # surface of its own.
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+          cache-suffix: toolchain-free
+          cache-python: true
+      - name: Build an environment with no documentation toolchain in it
+        run: |
+          uv venv /tmp/toolchain-free
+          uv pip install --python /tmp/toolchain-free --no-sources "packages/sphinx-test-reports[pytest]"
+      - name: Assert the toolchain really is absent
+        # the fence's fence. Without this the job would still pass with Sphinx installed,
+        # and would be testing nothing it claims to test.
+        run: |
+          /tmp/toolchain-free/bin/python -c "
+          import importlib.util, sys
+          present = [m for m in ('sphinx', 'sphinx_needs', 'docutils') if importlib.util.find_spec(m)]
+          sys.exit(f'toolchain installed: {present}' if present else 0)
+          "
+      - name: Run the modules that need no documentation build
+        # From the REPOSITORY ROOT, so pytest's rootdir is this repository and the root
+        # `[tool.pytest.ini_options]` applies -- which is where the `toolchain` marker is
+        # registered, so `-m "not toolchain"` deselects rather than warning.
+        run: |
+          /tmp/toolchain-free/bin/python -m pytest -q -m "not toolchain" \
+            packages/sphinx-test-reports/tests/test_cli_config.py \
+            packages/sphinx-test-reports/tests/test_cli_convert.py \
+            packages/sphinx-test-reports/tests/test_identity.py \
+            packages/sphinx-test-reports/tests/test_junit_parser.py \
+            packages/sphinx-test-reports/tests/test_junit_parser_gtest.py \
+            packages/sphinx-test-reports/tests/test_needs_export.py \
+            packages/sphinx-test-reports/tests/test_project_config.py \
+            packages/sphinx-test-reports/tests/test_pytest_plugin.py \
+            packages/sphinx-test-reports/tests/test_result_vocabulary.py \
+            packages/sphinx-test-reports/tests/test_toolchain.py
+
   bazel:
     name: Mounts Bazel integration
     runs-on: ubuntu-latest
@@ -419,7 +529,7 @@ jobs:
       - uses: actions/checkout@v7
       - name: Install graphviz
         run: sudo apt-get install graphviz
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           cache-suffix: bazel
@@ -460,7 +570,7 @@ jobs:
       - uses: actions/checkout@v7
       - name: Install graphviz
         run: sudo apt-get install graphviz
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           # the declared `requires-python` floor: the throwaway environment the wheel is
@@ -485,6 +595,8 @@ jobs:
       - tests-no-mpl
       - tests-extensions
       - docs-codelinks
+      - docs-reports
+      - toolchain-free
       - bazel
       - smoke-needs
 

.github/workflows/copilot-setup-steps.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v7
 
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           # 3.12+: on 3.11 the lock resolves sphinx 8.2, and this job wants the newest sphinx

.github/workflows/docs.yaml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           # 3.12+: on 3.11 the lock resolves sphinx 8.2, and this job wants the newest sphinx

.github/workflows/prek-update.yaml

@@ -27,7 +27,7 @@ jobs:
 
       - uses: actions/checkout@v7
 
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           # no `python-version` input, so uv reads the root `.python-version`; cache that

.github/workflows/release.yaml

@@ -49,7 +49,7 @@ jobs:
           # for the default depth-1 -- 14 seconds on a workflow whose compat cell takes
           # minutes, and the alternative is a check that cannot run
           fetch-depth: 0
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
       # `--no-project`: this fence reads the manifests, so it must not need an environment
       # built from them. It is also the only thing between a mistyped tag and an
       # unprotected environment, so it runs before anything else is built.
@@ -73,7 +73,7 @@ jobs:
         # skip without `dot`. This mirrors the core test cells in ci.yaml; java, which the
         # vendored plantuml jar needs, is already on the ubuntu runner image
         run: sudo apt-get install graphviz
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           # no `enable-cache`: setup-uv's own default is `auto`, which caches on
           # GitHub-hosted runners EXCEPT for release, tag push and a few other events --
@@ -155,11 +155,26 @@ jobs:
           # FileNotFoundError on a runner or -- worse, locally -- silently use whatever
           # `sphinx-build` an activated virtualenv happens to have left on PATH
           export PATH="/tmp/compat/bin:$PATH"
-          # both of these assume the distribution name IS the directory name and, with
-          # `-`->`_`, the module name. `check_workspace.py` deliberately honours
-          # `[tool.flit.module] name`, so a second member that sets it needs this step
-          # taught the same thing
-          module=${DIST//-/_}
+          # The distribution name IS the directory name, but it is NOT always the module
+          # name with `-`->`_`: sphinx-test-reports installs into the `sphinxcontrib`
+          # PEP 420 namespace and declares `[tool.flit.module] name =
+          # "sphinxcontrib.test_reports"`, for which the derivation below yields
+          # `sphinx_test_reports` -- a module that does not exist, so the walk would fail
+          # with `ModuleNotFoundError` on every release of it. `check_workspace.Member.module`
+          # has honoured that key from the start and this step now does too, falling back to
+          # the derivation for every member that declares no such table (all three others).
+          # The comment this replaces predicted exactly this member.
+          module=$(/tmp/compat/bin/python - "$DIST" <<'PYEOF'
+          import pathlib, sys, tomllib
+
+          dist = sys.argv[1]
+          manifest = pathlib.Path("packages", dist, "pyproject.toml")
+          data = tomllib.loads(manifest.read_text(encoding="utf-8"))
+          declared = data.get("tool", {}).get("flit", {}).get("module", {}).get("name")
+          print(declared or dist.replace("-", "_"))
+          PYEOF
+          )
+          echo "walking module: $module"
           # Import every module of the wheel BEFORE the suite. A name that is missing from
           # a dependency AS PUBLISHED is then reported in seconds, by name, instead of
           # somewhere inside a six-minute pytest run -- and `--expect-prefix` subsumes the
@@ -207,7 +222,7 @@ jobs:
         with:
           name: dist
           path: dist/
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
       # `always`, not `automatic`: `automatic` falls back to unauthenticated, and even a
       # dry run then exits 0 -- so a missing OIDC token would look like success.
       # `--no-attestations` only suppresses uploading attestation FILES that already sit

.github/workflows/test-extensions.yaml

@@ -57,7 +57,7 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           cache-suffix: ${{ inputs.cache-suffix }}
@@ -143,3 +143,25 @@ jobs:
           flags: codelinks
           files: ./codelinks.xml
           fail_ci_if_error: true
+      - name: "sphinx-test-reports: pytest"
+        # `!cancelled()` plus the prologue check, for the reason the step above gives: a
+        # failure in either suite before it must not hide this one, but a failed
+        # `prepare-cell` must, or `uv run --no-sync` silently creates an empty environment
+        # and the step dies on an import error four steps from the cause.
+        #
+        # `--cov=sphinxcontrib.test_reports` is the IMPORT name, which is not the
+        # distribution name with `-`->`_` for this member -- it installs into the
+        # `sphinxcontrib` PEP 420 namespace. This cell needs no new tool: nothing in this
+        # suite renders a diagram, so neither the graphviz nor the PlantUML the cell
+        # already installs for sphinx-mounts is for it.
+        if: ${{ !cancelled() && steps.prepare.outcome == 'success' }}
+        run: uv run --no-sync pytest -v packages/sphinx-test-reports/tests --durations=25 --cov=sphinxcontrib.test_reports --cov-report=xml:reports.xml --cov-report=term-missing
+      - name: "sphinx-test-reports: upload to Codecov"
+        if: inputs.upload-coverage && github.event.pull_request.head.repo.full_name == github.repository && github.repository == 'useblocks/sphinx-needs' && github.actor != 'dependabot[bot]'
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          name: sphinx-test-reports-pytests
+          flags: reports
+          files: ./reports.xml
+          fail_ci_if_error: true

.github/workflows/test-package.yaml

@@ -104,7 +104,7 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           cache-suffix: ${{ inputs.cache-suffix }}

.gitignore

@@ -21,6 +21,7 @@ coverage.xml
 # coverage report (`--cov-report=xml:<name>.xml`) instead of sharing `coverage.xml`
 mounts.xml
 codelinks.xml
+reports.xml
 .ty_cache
 
 # packages/sphinx-codelinks' tests write these at the CWD: `tests/test_cmd.py` writes