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

📚 sphinx-test-reports: the `tr_link` docs invert the two arguments and say "all other needs"; the `links_from_match` rewrite

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

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
66/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
documentation

Research direction

Start with the tr_link section of packages/sphinx-test-reports/docs/functions.rst and compare its argument descriptions with the function's code, where the first argument is read on the calling need and the second on every need. Correct the argument order and change "all other needs" so it reflects that the calling need is included. Check the behaviour the issue lists (duplicates per value, iteration order, the failure on list or integer fields) against the code so the docs state it accurately. The docs fix is done when the section matches the code; the deprecation is a separate maintainer decision.

Written by the indexing model from the issue text.

Description

documentation pkg: sphinx-test-reports
What

packages/sphinx-test-reports/docs/functions.rst (the tr_link section) describes the two arguments the other way round from the code, and says the function searches "all other needs" while the calling need is included.

Measured (monorepo 05b4fd2d, sphinx-test-reports 3.0.0; ~/GitHub/ubcode-orchestration/fable/archive/join/join-recon.md J6 for the whole table)

tr_link(app, need, needs, test_option, target_option): the FIRST argument is read on the calling need, split on , and stripped; the SECOND is read on every need and compared whole. So tr_link('ref', 'name') reads ref on this need and name on every need. The docs page states it inverted. And TEST_SELF with :ref: SELFV :name: SELFV links itself — the reader is a candidate.

Other measured facts the docs do not say: a need matched by several of the reader's values is linked once PER value (duplicates); the links come in the project's iteration order (not need-id order); a comma-separated candidate value never matches (compared whole); a list-valued or integer reader field fails the call ('list' object has no attribute 'split'); a list or integer candidate never matches.

Ask

Fix the argument description and "all other needs". Since 9.1.0 (#2228) sphinx-needs' built-in links_from_match(field, equals, include_self=False, filter=None) computes the same links for the documented usages, with the arguments SWAPPED ([[links_from_match('name', 'ref', include_self=True)]] for tr_link('ref', 'name')), each match once, in need-id order, both sides split; ubCode resolves it. The planned deprecation of tr_link (a warning naming that rewrite in the next minor; the alias in the next major, with a "(changed output)" line for the differences above) is pending the maintainer's decision on timing; this issue tracks the docs fix at least. Related: #1966 (matching on more than one option at once is what the split gives), #1955 (need parts: a join matches needs only).

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.