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

🐛 A needextend in a project with no needs crashes the HTML build

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

Research direction

The crash comes from the early return in the doctree-resolved handler in directives/need.py, which runs before the Needextend nodes are removed (around lines 420-423). Reproduce with the two-file project from the issue and sphinx-build -b html . _build. Done when that build exits 0 and the early return no longer skips removal of Needextend nodes; also check whether other node types skipped by the same return need the same treatment.

Written by the indexing model from the issue text.

Description

bug pkg: sphinx-needs

Reproduction

Measured at master 26cc211 with Sphinx 9.1.0.

conf.py:

extensions = ["sphinx_needs"]

index.rst:

Test
====

.. needextend:: NOPE
   :status: done

sphinx-build -b html . _build exits with code 2:

NotImplementedError: <class 'sphinx.writers.html5.HTML5Translator'> departing unknown node type: Needextend

If you add one need to the page, the same needextend builds (exit 0).

Cause

In directives/need.py, the doctree-resolved handler returns early when the project has no needs. It does this before it removes the Needextend nodes:

# If no needs were defined, we do not need to do anything
if not needs_data.get_needs_view():          # :420
    return

for extend_node in list(doctree.findall(Needextend)):   # :423
    remove_node_from_tree(extend_node)

So the node reaches the HTML writer, which has no visitor for it.

Expected

The build succeeds. The needextend matches nothing and is reported the way it is when a project has needs. The Needextend nodes are removed whether or not there are needs. Other node types that the same early return skips may need the same treatment; that is worth checking.

Found while measuring the per-type docs (#2295).

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

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.