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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
import py
from pypy.tool.rest.rst import Rest, Paragraph, Strong, ListItem, Title, Link
from pypy.tool.rest.rst import Directive, Text
from rpython.config.config import ChoiceOption, BoolOption, StrOption, IntOption
from rpython.config.config import FloatOption, OptionDescription, Option, Config
from rpython.config.config import ArbitraryOption, DEFAULT_OPTION_NAME
from rpython.config.config import _getnegation
configdocdir = py.path.local(__file__).dirpath().dirpath().join("doc", "config")
def get_fullpath(opt, path):
if path:
return "%s.%s" % (path, opt._name)
else:
return opt._name
def get_cmdline(cmdline, fullpath):
if cmdline is DEFAULT_OPTION_NAME:
return '--%s' % (fullpath.replace('.', '-'),)
else:
return cmdline
class __extend__(Option):
def make_rest_doc(self, path=""):
fullpath = get_fullpath(self, path)
result = Rest(
Title(fullpath, abovechar="=", belowchar="="),
ListItem(Strong("name:"), self._name),
ListItem(Strong("description:"), self.doc))
if self.cmdline is not None:
cmdline = get_cmdline(self.cmdline, fullpath)
result.add(ListItem(Strong("command-line:"), cmdline))
return result
class __extend__(ChoiceOption):
def make_rest_doc(self, path=""):
content = super(ChoiceOption, self).make_rest_doc(path)
content.add(ListItem(Strong("option type:"), "choice option"))
content.add(ListItem(Strong("possible values:"),
*[ListItem(str(val)) for val in self.values]))
if self.default is not None:
content.add(ListItem(Strong("default:"), str(self.default)))
requirements = []
for val in self.values:
if val not in self._requires:
continue
req = self._requires[val]
requirements.append(ListItem("value '%s' requires:" % (val, ),
*[ListItem(Link(opt, opt + ".html"),
"to be set to '%s'" % (rval, ))
for (opt, rval) in req]))
if requirements:
content.add(ListItem(Strong("requirements:"), *requirements))
return content
class __extend__(BoolOption):
def make_rest_doc(self, path=""):
content = super(BoolOption, self).make_rest_doc(path)
fullpath = get_fullpath(self, path)
if self.negation and self.cmdline is not None:
if self.cmdline is DEFAULT_OPTION_NAME:
cmdline = '--%s' % (fullpath.replace('.', '-'),)
else:
cmdline = self.cmdline
neg_cmdline = ["--" + _getnegation(argname.lstrip("-"))
for argname in cmdline.split()
if argname.startswith("--")][0]
content.add(ListItem(Strong("command-line for negation:"),
neg_cmdline))
content.add(ListItem(Strong("option type:"), "boolean option"))
if self.default is not None:
content.add(ListItem(Strong("default:"), str(self.default)))
if self._requires is not None:
requirements = [ListItem(Link(opt, opt + ".html"),
"must be set to '%s'" % (rval, ))
for (opt, rval) in self._requires]
if requirements:
content.add(ListItem(Strong("requirements:"), *requirements))
if self._suggests is not None:
suggestions = [ListItem(Link(opt, opt + ".html"),
"should be set to '%s'" % (rval, ))
for (opt, rval) in self._suggests]
if suggestions:
content.add(ListItem(Strong("suggestions:"), *suggestions))
return content
class __extend__(IntOption):
def make_rest_doc(self, path=""):
content = super(IntOption, self).make_rest_doc(path)
content.add(ListItem(Strong("option type:"), "integer option"))
if self.default is not None:
content.add(ListItem(Strong("default:"), str(self.default)))
return content
class __extend__(FloatOption):
def make_rest_doc(self, path=""):
content = super(FloatOption, self).make_rest_doc(path)
content.add(ListItem(Strong("option type:"), "float option"))
if self.default is not None:
content.add(ListItem(Strong("default:"), str(self.default)))
return content
class __extend__(StrOption):
def make_rest_doc(self, path=""):
content = super(StrOption, self).make_rest_doc(path)
content.add(ListItem(Strong("option type:"), "string option"))
if self.default is not None:
content.add(ListItem(Strong("default:"), str(self.default)))
return content
class __extend__(ArbitraryOption):
def make_rest_doc(self, path=""):
content = super(ArbitraryOption, self).make_rest_doc(path)
content.add(ListItem(Strong("option type:"),
"arbitrary option (mostly internal)"))
if self.default is not None:
content.add(ListItem(Strong("default:"), str(self.default)))
elif self.defaultfactory is not None:
content.add(ListItem(Strong("factory for the default value:"),
str(self.defaultfactory)))
return content
class __extend__(OptionDescription):
def make_rest_doc(self, path=""):
fullpath = get_fullpath(self, path)
content = Rest(
Title(fullpath, abovechar="=", belowchar="="))
toctree = []
for child in self._children:
subpath = fullpath + "." + child._name
toctree.append(subpath)
content.add(Directive("toctree", *toctree, **{'maxdepth': 4}))
content.join(
ListItem(Strong("name:"), self._name),
ListItem(Strong("description:"), self.doc))
return content
def _get_section_header(cmdline, fullpath, subdescr):
# XXX: pypy specific hack
txtfile = configdocdir.join(fullpath + ".txt")
if not txtfile.check():
print txtfile, "not found"
return ""
content = txtfile.read()
if ".. internal" in content:
return "Internal Options"
return ""
def make_cmdline_overview(descr, title=True):
content = Rest()
if title:
content.add(
Title("Overview of Command Line Options for '%s'" % (descr._name, ),
abovechar="=", belowchar="="))
cmdlines = []
config = Config(descr)
for path in config.getpaths(include_groups=False):
subconf, step = config._cfgimpl_get_home_by_path(path)
fullpath = (descr._name + "." + path)
subdescr = getattr(subconf._cfgimpl_descr, step)
cmdline = get_cmdline(subdescr.cmdline, fullpath)
if cmdline is not None:
header = _get_section_header(cmdline, fullpath, subdescr)
cmdlines.append((header, cmdline, fullpath, subdescr))
cmdlines.sort(key=lambda x: (x[0], x[1].strip("-")))
currheader = ""
curr = content
for header, cmdline, fullpath, subdescr in cmdlines:
if header != currheader:
content.add(Title(header, abovechar="", belowchar="="))
curr = content.add(Paragraph())
currheader = header
curr.add(ListItem(Link(cmdline + ":", fullpath + ".html"),
Text(subdescr.doc)))
return content
def register_config_role(docdir):
""" register a :config: ReST link role for use in documentation. """
try:
from docutils.parsers.rst import directives, states, roles
from pypy.tool.rest.directive import register_linkrole
except ImportError:
return
# enable :config: link role
def config_role(name, rawtext, text, lineno, inliner, options={},
content=[]):
from docutils import nodes
from pypy.config.pypyoption import get_pypy_config
from pypy.config.makerestdoc import get_cmdline
txt = docdir.join("config", text + ".rst")
html = docdir.join("config", text + ".html")
assert txt.check()
assert name == "config"
sourcedir = py.path.local(inliner.document.settings._source).dirpath()
curr = sourcedir
prefix = ""
while 1:
relative = str(html.relto(curr))
if relative:
break
curr = curr.dirpath()
prefix += "../"
config = get_pypy_config()
# begin horror
h, n = config._cfgimpl_get_home_by_path(text)
opt = getattr(h._cfgimpl_descr, n)
# end horror
cmdline = get_cmdline(opt.cmdline, text)
if cmdline is not None:
shortest_long_option = 'X'*1000
for cmd in cmdline.split():
if cmd.startswith('--') and len(cmd) < len(shortest_long_option):
shortest_long_option = cmd
text = shortest_long_option
target = prefix + relative
reference_node = nodes.reference(rawtext, text, name=text, refuri=target)
return [reference_node], []
config_role.content = True
config_role.options = {}
return config_role
|
