sphinx-doc/sphinx

DRY: refactor common functionality in generating index nodes

Open

#2,914 opened on Aug 26, 2016

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

Repository metrics

Stars
 (5,625 stars)
PR merge metrics
 (Avg merge 10d 11h) (11 merged PRs in 30d)

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

Research direction
Identify the common pattern in the three referenced code snippets and extract it into a single utility function. Ensure the function is flexible enough to be used by extensions.
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.
2
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.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GitPython
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75