sphinx-doc/sphinx

DRY: refactor common functionality in generating index nodes

Open

#2,914 opened on 2016年8月26日

GitHub で見る
 (5 comments) (0 reactions) (0 assignees)Python (5,625 stars) (1,985 forks)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
Issue 種別
refactor
難度新しい貢献者にとっての実装難度です。1 は非常に小さな変更、5 は専門的な作業です。
3
推定時間経験ある貢献者が調査、実装、テスト、pull request 準備にかけるおおよその時間範囲です。
1-3 hours
活動状況Issue が今どれだけ取り組みやすいかを示します。新しい、活発、古い、ブロック中、またはメンテナー入力待ちなどです。
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.