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

šŸ› A `:hide:` need that is the first child of its container gets empty `sections` and no `signature`

Open Beginner friendly
  • Is something wrong?
#2,398 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
78/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend

Research direction

Start in packages/sphinx-needs/src/sphinx_needs/directives/need.py, at analyse_need_locations and get_sections_and_signature_and_needs. Trace how the walk begins for hidden and visible needs, then add or locate regression tests for a hidden need as the first child of each affected container. Done means its sections and, inside a function body, signature match the visible-need case.

Written by the indexing model from the issue text.

Description

bug pkg: sphinx-needs
What happens

A need with :hide: that is the first child of its container gets empty sections and no signature, although it sits inside sections and, possibly, inside a domain object. Containers where this happens include a .. only:: block, a .. note::, a parent need's content, and the body of a py:function.

The cause is in analyse_need_locations (packages/sphinx-needs/src/sphinx_needs/directives/need.py:336). It starts the walk at previous_sibling(need_node), not at the need's own node. A visible need's previous sibling is its own nodes.target, so the walk climbs from there. A hidden need has no target, so as a first child it has no previous sibling at all. get_sections_and_signature_and_needs(None) then walks nothing and returns [], None.

Controls that are right: a hidden need right after a title, after a paragraph, or after another hidden need.

Reproduction
Top
===

Sub
---

.. only:: html

   .. req:: Hidden first child
      :id: H_ONLY
      :hide:

H_ONLY gets sections == [], where a visible need in the same place gets ['Sub', 'Top']. The same holds for a :hide: need first inside .. note::, first in a parent need's content, or first in a .. py:function:: body (which also loses that function's signature).

Fix

Start the walk from the need's own node, or from its target when it has one, so that a hidden need is located exactly as a visible one is. This changes sections and signature only for hidden needs that are a first child, and those values were wrong.

Dominant language
Python
Stars
309
Forks
103
Avg merge
4h 26m
Merged PRs (30d)
163

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.