Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

🐛 sphinx-test-reports: six test-report template findings from ubCode's port — crashing checks, an absolute {template_path}, template positions, {content}'s indent, MyST, section nesting

Open
  • Is something wrong?
#2,188 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
documentation, testing

Research direction

Start with test_report.py and the test-report directive, then compare the six measured findings against the referenced issues and ubCode's divergence register. Check how template loading, parsing, positions, content indentation, and MyST handling are covered by tests; the issue proposes separate fixes and documentation, so done means each picked-up item has a located, verified behavior matching the agreed rule.

Written by the indexing model from the issue text.

Description

bug P3 pkg: sphinx-test-reports

Six findings on the test-report directive, measured while porting it to ubCode (useblocks/ubcode#3942; the measurements are at monorepo commit 7be5bf53, sphinx-test-reports 2.0.0). Collected in one issue rather than six; split out whatever gets picked up. Each item says what ubCode's port does, where the two differ — ubCode registers every such row in its design/divergence-register.md, and the two tools should agree on the rule even where the fix lands later.

1. A template mistake is checked by crashing

Every mistake in a report template aborts the build, unlocated, at the first test-report that renders it: an unknown key (KeyError: 'unknown'), a lone { or } (ValueError: unexpected '{' in field name / Single '}' encountered), a positional field (IndexError: Replacement index 0 out of range), a format spec (ValueError: Unknown format code 'T'), a missing template (InvalidConfigurationError: could not find a template file with name … in conf.py directory), a Latin-1 file read as UTF-8 (UnicodeDecodeError), a directive without :id: (SphinxError: ID must be set for test-report.) or without :file: (TestReportFileNotSetError). Four constructs render silently, one of them as a memory address: {id.upper} → <built-in method upper of str object at 0x…>.

Not in #2052's table (no template row) nor in #2050 / #2138–#2141 / #1959. Proposal: declare the template grammar — {key} for the ten keys of template_data plus {{ / }} — and make every other construct, and every missing input, a located test_reports.* warning with an error box, the shape #2156–#2162 gave the other directives. ubCode: that grammar; every construct above is a positioned finding naming the template and its line; the build goes on. Pairs with #2063 (specify the report grammar).

2. {template_path} publishes an absolute filesystem path

For the shipped default it is the installed package's …/site-packages/sphinx_test_reports/directives/test_report_template.txt; for a configured one, wherever the file sits on the build machine. Machine-specific text in the page, the twin of #2125's {file} fix. Proposal: the path relative to confdir (the TOML directory under ubproject), and the file name alone for the shipped default. ubCode: relative to the ubproject.toml that set it.

3. Positions inside the spliced template are fiction

docutils reports the HOST page's path with the TEMPLATE's line (index.rst:3, :7, :9 for an 8-line host), while self.lineno-based reports and the generated needs carry the COMBINED line (index.rst:52 on a 9-line host; lineno = 143 in needs.json for a need on a 17-line page). #2162 attributes every generated line to the test-report's own line, which closes the second half; the first half — a parse problem inside the template named with the host's path and the template's line — stands. Proposal: pass the template path as insert_input's source (docutils then names template:line), or map through the directive's line as #2162 does. ubCode: a template line's finding sits on the directive's name with in the test-report template <path>:<line>: prefixed; a body line's finding on the body's own page line (#2187 is the body half on this side).

4. {content}'s indent comes from the first line containing {content}

_CONTENT_INDENT (test_report.py) takes the indentation of the first template line that contains the text {content}: an escaped {{content}} earlier in the template sets it (measured: "Explicit markup ends without a blank line" on the real one), and one indent serves every placeholder — a second {content} at column 0 renders the body as a definition list. Also: the utf8 codec keeps a byte-order mark, rendered as U+FEFF at the top of the page. Minor; the shipped template is unaffected. ubCode: each {content} takes its own line's indent; a BOM is dropped.

5. test-report cannot run in a MyST page

mpage.md:3: ERROR: Directive 'test-report' cannot be mocked: MockingError: MockStateMachine has not yet implemented attribute 'insert_input'; nothing rendered. Proposal: document it under the directive, or splice through a nested parse instead of insert_input (which would also give item 3 its real positions). ubCode: a located finding (needs.test_report_markdown_host), nothing rendered.

6. (docs) A custom template's section joins the host's title-style table

A ===-underlined section in the template becomes a top-level sibling of the page title and re-parents the host's following --- sections. docutils' include semantics, so not a bug — worth one sentence under tr_report_template. ubCode: the same (the include rule); documented in its differences.rst.

Dominant language
Python
Stars
309
Forks
103
Avg merge
10h 41m
Merged PRs (30d)
128

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from useblocks/sphinx-needs

All issues in useblocks/sphinx-needs

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.