sphinx-doc/sphinx

DRY: refactor common functionality in generating index nodes

Open

#2,914 建立於 2016年8月26日

在 GitHub 查看
 (5 留言) (0 反應) (0 負責人)Python (5,625 star) (1,985 fork)batch import
good first issuehelp wantedtype:enhancement

描述

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.

貢獻者指南

技術棧
python
領域
documentation
議題類型
refactor
難度面向新貢獻者的預計實作難度，1 表示很小改動，5 表示專家級工作。
3
預計時間有經驗貢獻者完成調查、實作、測試並準備 pull request 的粗略時間範圍。
1-3 hours
活動狀態議題目前的可參與程度：新鮮、活躍、陳舊、阻塞或等待維護者輸入。
stale
清晰度議題是否清楚說明預期改動、驗收標準和下一步。
clear
前置要求
PythonSphinx internals
新手友善度1-100 的估計分數，表示該議題對首次貢獻者的友善程度。
60
研究方向
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.