sphinx-doc/sphinx

DRY: refactor common functionality in generating index nodes

Open

#2914 opened on Aug 26, 2016

View on GitHub
 (5 comments) (0 reactions) (0 assignees)Python (5,625 stars) (1,985 forks)batch import
good first issuehelp wantedtype:enhancement

Description

I am trying to write a simple extension to automatically add some index nodes. Unfortunately there doesn't seem to be any base function to do that. I found three places where the same essential stuff is being used to add index nodes to the toctree:

So it looks like I have to copy the appropriate implementation pieces of this (add a target node, add an index node, configure each of them).

It would be really useful to refactor the common functionality into a single, simple function that extensions could use.

Contributor guide

Tech stack
python
Domain
documentation
Issue type
refactor
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
PythonSphinx internals
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
The issue identifies three locations in the Sphinx codebase where similar logic for adding index nodes is used: sphinx/domains/std.py line 95, sphinx/roles.py line 170, and sphinx/directives/other.py line 163. The goal is to extract this common functionality into a single reusable function that can be used by extensions. A contributor should study these three code snippets, identify the common pattern, and create a new function or method in an appropriate module (e.g., sphinx/util/nodes.py) that encapsulates the logic. Ensure that the refactored code maintains backward compatibility and updates all three call sites.