✨ sphinx-needs: decide how a hidden need's content is processed (content_links, links_from_content, references)
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 45/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- python
- Domain
- documentation
Research direction
Read the hidden-need handling and derive-rule code, then inspect the conformance corpus and the referenced ubCode register entry at design/divergence-register.md. Decide whether hidden content remains unprocessed or follows visible-need behavior; update the derive kinds consistently and add the content-links-hidden corpus case. Done when the decision is documented and the corpus and divergence register reflect it.
Written by the indexing model from the issue text.
Description
The question
A :hide: need's content is not rendered, and today it is not processed either: no node is stored for it, so a content_links derive rule and the inline links_from_content() on a hidden need give [] with the links_from_content: no stored node for need 'X' [needs.dynamic_function] warning, and a visible need's rule with from = "X" naming a hidden need gives the same. The references inside its content reach no backlink.
#2191 first shipped a change that read a hidden need's content references anyway (a scratch document per hidden need, with a page-leak fix), and it was taken out before merge because it touched how hidden needs are handled in general, which deserves its own decision rather than a side effect of the derive kinds. 9.0.0 therefore keeps the pre-existing behaviour, the corpus leaves the case unpinned, and ubCode registers the divergence (it reads a hidden need's references at parse time).
Options
- Keep hidden content unprocessed (status quo): document it;
links_from_contenton a hidden need stays[]+ the warning. - Process a hidden need's content like a visible one's but render nothing: references, backlinks,
content_linksall work; this is what ubCode does (it renders hidden needs fully, collapsed) — the natural parity choice. - Render hidden needs collapsed, as ubCode does, which makes 2 the consequence rather than a special case.
Related: #1433 (hidden needs get a parent_need link they should not), which is the same seam.
When decided
The derive kinds follow the decision (one rule, no special case); the conformance corpus gains the content-links-hidden case; ubCode's register row closes (useblocks/ubcode, design/divergence-register.md, "a hidden need's content references").
- Dominant language
- Python
- Stars
- 309
- Forks
- 103
- Avg merge
- 11h 26m
- Merged PRs (30d)
- 118
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from useblocks/sphinx-needs
-
documentation pkg: sphinx-needs
Difficulty 1/5 Under an hour Newbie friendliness 82/100
useblocks/sphinx-needs#2255 ·
Maintainers usually reply within 1 day
-
bug pkg: sphinx-needs
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
useblocks/sphinx-needs#2253 ·
Maintainers usually reply within 1 day
-
bug pkg: sphinx-needs
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
useblocks/sphinx-needs#2251 ·
Maintainers usually reply within 1 day
-
bug pkg: sphinx-needs
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
useblocks/sphinx-needs#2249 ·
Maintainers usually reply within 1 day
-
documentation pkg: sphinx-test-reports
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
useblocks/sphinx-needs#2247 ·
Maintainers usually reply within 1 day
All issues in useblocks/sphinx-needs
Similar issues
-
fix formatting of the sample database page of the docsPossibly taken @Aaqibhafeezkhan claimed this today. Opendocumentation good first issue help wanted
Difficulty 1/5 Under an hour Newbie friendliness 72/100
chaoss/CollectOSS#544 · 1 comment ·
Maintainers usually reply within 1 day
-
area/plugin good first issue
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
kestra-io/plugin-soda#137 ·
-
Difficulty 2/5 Half a day Newbie friendliness 62/100
ibm-granite/granite.build#504 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day