1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
# pylint: disable=import-error
from collections.abc import Sequence
from operator import itemgetter
from typing import Any, TypedDict
from docutils import nodes
from docutils.nodes import Element, General, Node, document
from docutils.parsers.rst import Directive
from sphinx.application import Sphinx
from sphinx.util.nodes import make_refnode
class SettingData(TypedDict):
docname: str
setting_name: str
refid: str
class SettingslistNode(General, Element):
pass
class SettingsListDirective(Directive):
def run(self) -> Sequence[Node]:
return [SettingslistNode()]
def is_setting_index(node: Node) -> bool:
if node.tagname == "index" and node["entries"]: # type: ignore[index,attr-defined]
# index entries for setting directives look like:
# [('pair', 'SETTING_NAME; setting', 'std:setting-SETTING_NAME', '')]
entry_type, info, refid = node["entries"][0][:3] # type: ignore[index]
return entry_type == "pair" and info.endswith("; setting")
return False
def get_setting_name_and_refid(node: Node) -> tuple[str, str]:
"""Extract setting name from directive index node"""
entry_type, info, refid = node["entries"][0][:3] # type: ignore[index]
return info.replace("; setting", ""), refid
def collect_scrapy_settings_refs(app: Sphinx, doctree: document) -> None:
env = app.builder.env
if not hasattr(env, "scrapy_all_settings"):
emptyList: list[SettingData] = []
env.scrapy_all_settings = emptyList # type: ignore[attr-defined]
for node in doctree.findall(is_setting_index):
setting_name, refid = get_setting_name_and_refid(node)
env.scrapy_all_settings.append( # type: ignore[attr-defined]
SettingData(
docname=env.docname,
setting_name=setting_name,
refid=refid,
)
)
def make_setting_element(
setting_data: SettingData, app: Sphinx, fromdocname: str
) -> Any:
refnode = make_refnode(
app.builder,
fromdocname,
todocname=setting_data["docname"],
targetid=setting_data["refid"],
child=nodes.Text(setting_data["setting_name"]),
)
p = nodes.paragraph()
p += refnode
item = nodes.list_item()
item += p
return item
def replace_settingslist_nodes(
app: Sphinx, doctree: document, fromdocname: str
) -> None:
env = app.builder.env
for node in doctree.findall(SettingslistNode):
settings_list = nodes.bullet_list()
settings_list.extend(
[
make_setting_element(d, app, fromdocname)
for d in sorted(env.scrapy_all_settings, key=itemgetter("setting_name")) # type: ignore[attr-defined]
if fromdocname != d["docname"]
]
)
node.replace_self(settings_list)
def source_role(
name, rawtext, text: str, lineno, inliner, options=None, content=None
) -> tuple[list[Any], list[Any]]:
ref = "https://github.com/scrapy/scrapy/blob/master/" + text
node = nodes.reference(rawtext, text, refuri=ref, **options)
return [node], []
def issue_role(
name, rawtext, text: str, lineno, inliner, options=None, content=None
) -> tuple[list[Any], list[Any]]:
ref = "https://github.com/scrapy/scrapy/issues/" + text
node = nodes.reference(rawtext, "issue " + text, refuri=ref)
return [node], []
def commit_role(
name, rawtext, text: str, lineno, inliner, options=None, content=None
) -> tuple[list[Any], list[Any]]:
ref = "https://github.com/scrapy/scrapy/commit/" + text
node = nodes.reference(rawtext, "commit " + text, refuri=ref)
return [node], []
def rev_role(
name, rawtext, text: str, lineno, inliner, options=None, content=None
) -> tuple[list[Any], list[Any]]:
ref = "http://hg.scrapy.org/scrapy/changeset/" + text
node = nodes.reference(rawtext, "r" + text, refuri=ref)
return [node], []
def setup(app: Sphinx) -> None:
app.add_crossref_type(
directivename="setting",
rolename="setting",
indextemplate="pair: %s; setting",
)
app.add_crossref_type(
directivename="signal",
rolename="signal",
indextemplate="pair: %s; signal",
)
app.add_crossref_type(
directivename="command",
rolename="command",
indextemplate="pair: %s; command",
)
app.add_crossref_type(
directivename="reqmeta",
rolename="reqmeta",
indextemplate="pair: %s; reqmeta",
)
app.add_role("source", source_role)
app.add_role("commit", commit_role)
app.add_role("issue", issue_role)
app.add_role("rev", rev_role)
app.add_node(SettingslistNode)
app.add_directive("settingslist", SettingsListDirective)
app.connect("doctree-read", collect_scrapy_settings_refs)
app.connect("doctree-resolved", replace_settingslist_nodes)
|
