Python code coverage for Doc/tools/sphinxext/pyspecific.py

#	count	content
1	n/a	# -- coding: utf-8 --
2	n/a	"""
3	n/a	pyspecific.py
4	n/a	~~~~~~~~~~~~~
5	n/a
6	n/a	Sphinx extension with Python doc-specific markup.
7	n/a
8	n/a	:copyright: 2008, 2009, 2010, 2011, 2012 by Georg Brandl.
9	n/a	:license: Python license.
10	n/a	"""
11	n/a
12	n/a	ISSUE_URI = 'http://bugs.python.org/issue%s'
13	n/a	SOURCE_URI = 'http://hg.python.org/cpython/file/default/%s'
14	n/a
15	n/a	from docutils import nodes, utils
16	n/a	from sphinx.util.nodes import split_explicit_title
17	n/a
18	n/a	# monkey-patch reST parser to disable alphabetic and roman enumerated lists
19	n/a	from docutils.parsers.rst.states import Body
20	n/a	Body.enum.converters['loweralpha'] = \
21	n/a	Body.enum.converters['upperalpha'] = \
22	n/a	Body.enum.converters['lowerroman'] = \
23	n/a	Body.enum.converters['upperroman'] = lambda x: None
24	n/a
25	n/a	# monkey-patch HTML translator to give versionmodified paragraphs a class
26	n/a	def new_visit_versionmodified(self, node):
27	n/a	self.body.append(self.starttag(node, 'p', CLASS=node['type']))
28	n/a	text = versionlabels[node['type']] % node['version']
29	n/a	if len(node):
30	n/a	text += ':'
31	n/a	else:
32	n/a	text += '.'
33	n/a	self.body.append('<span class="versionmodified">%s</span> ' % text)
34	n/a
35	n/a	from sphinx.writers.html import HTMLTranslator
36	n/a	from sphinx.writers.latex import LaTeXTranslator
37	n/a	from sphinx.locale import versionlabels
38	n/a	HTMLTranslator.visit_versionmodified = new_visit_versionmodified
39	n/a	HTMLTranslator.visit_versionmodified = new_visit_versionmodified
40	n/a
41	n/a	# monkey-patch HTML and LaTeX translators to keep doctest blocks in the
42	n/a	# doctest docs themselves
43	n/a	orig_visit_literal_block = HTMLTranslator.visit_literal_block
44	n/a	def new_visit_literal_block(self, node):
45	n/a	meta = self.builder.env.metadata[self.builder.current_docname]
46	n/a	old_trim_doctest_flags = self.highlighter.trim_doctest_flags
47	n/a	if 'keepdoctest' in meta:
48	n/a	self.highlighter.trim_doctest_flags = False
49	n/a	try:
50	n/a	orig_visit_literal_block(self, node)
51	n/a	finally:
52	n/a	self.highlighter.trim_doctest_flags = old_trim_doctest_flags
53	n/a
54	n/a	HTMLTranslator.visit_literal_block = new_visit_literal_block
55	n/a
56	n/a	orig_depart_literal_block = LaTeXTranslator.depart_literal_block
57	n/a	def new_depart_literal_block(self, node):
58	n/a	meta = self.builder.env.metadata[self.curfilestack[-1]]
59	n/a	old_trim_doctest_flags = self.highlighter.trim_doctest_flags
60	n/a	if 'keepdoctest' in meta:
61	n/a	self.highlighter.trim_doctest_flags = False
62	n/a	try:
63	n/a	orig_depart_literal_block(self, node)
64	n/a	finally:
65	n/a	self.highlighter.trim_doctest_flags = old_trim_doctest_flags
66	n/a
67	n/a	LaTeXTranslator.depart_literal_block = new_depart_literal_block
68	n/a
69	n/a	# Support for marking up and linking to bugs.python.org issues
70	n/a
71	n/a	def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
72	n/a	issue = utils.unescape(text)
73	n/a	text = 'issue ' + issue
74	n/a	refnode = nodes.reference(text, text, refuri=ISSUE_URI % issue)
75	n/a	return [refnode], []
76	n/a
77	n/a
78	n/a	# Support for linking to Python source files easily
79	n/a
80	n/a	def source_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
81	n/a	has_t, title, target = split_explicit_title(text)
82	n/a	title = utils.unescape(title)
83	n/a	target = utils.unescape(target)
84	n/a	refnode = nodes.reference(title, title, refuri=SOURCE_URI % target)
85	n/a	return [refnode], []
86	n/a
87	n/a
88	n/a	# Support for marking up implementation details
89	n/a
90	n/a	from sphinx.util.compat import Directive
91	n/a
92	n/a	class ImplementationDetail(Directive):
93	n/a
94	n/a	has_content = True
95	n/a	required_arguments = 0
96	n/a	optional_arguments = 1
97	n/a	final_argument_whitespace = True
98	n/a
99	n/a	def run(self):
100	n/a	pnode = nodes.compound(classes=['impl-detail'])
101	n/a	content = self.content
102	n/a	add_text = nodes.strong('CPython implementation detail:',
103	n/a	'CPython implementation detail:')
104	n/a	if self.arguments:
105	n/a	n, m = self.state.inline_text(self.arguments[0], self.lineno)
106	n/a	pnode.append(nodes.paragraph('', '', *(n + m)))
107	n/a	self.state.nested_parse(content, self.content_offset, pnode)
108	n/a	if pnode.children and isinstance(pnode[0], nodes.paragraph):
109	n/a	pnode[0].insert(0, add_text)
110	n/a	pnode[0].insert(1, nodes.Text(' '))
111	n/a	else:
112	n/a	pnode.insert(0, nodes.paragraph('', '', add_text))
113	n/a	return [pnode]
114	n/a
115	n/a
116	n/a	# Support for documenting decorators
117	n/a
118	n/a	from sphinx import addnodes
119	n/a	from sphinx.domains.python import PyModulelevel, PyClassmember
120	n/a
121	n/a	class PyDecoratorMixin(object):
122	n/a	def handle_signature(self, sig, signode):
123	n/a	ret = super(PyDecoratorMixin, self).handle_signature(sig, signode)
124	n/a	signode.insert(0, addnodes.desc_addname('@', '@'))
125	n/a	return ret
126	n/a
127	n/a	def needs_arglist(self):
128	n/a	return False
129	n/a
130	n/a	class PyDecoratorFunction(PyDecoratorMixin, PyModulelevel):
131	n/a	def run(self):
132	n/a	# a decorator function is a function after all
133	n/a	self.name = 'py:function'
134	n/a	return PyModulelevel.run(self)
135	n/a
136	n/a	class PyDecoratorMethod(PyDecoratorMixin, PyClassmember):
137	n/a	def run(self):
138	n/a	self.name = 'py:method'
139	n/a	return PyClassmember.run(self)
140	n/a
141	n/a
142	n/a	# Support for documenting version of removal in deprecations
143	n/a
144	n/a	from sphinx.locale import versionlabels
145	n/a	from sphinx.util.compat import Directive
146	n/a
147	n/a	versionlabels['deprecated-removed'] = \
148	n/a	'Deprecated since version %s, will be removed in version %s'
149	n/a
150	n/a	class DeprecatedRemoved(Directive):
151	n/a	has_content = True
152	n/a	required_arguments = 2
153	n/a	optional_arguments = 1
154	n/a	final_argument_whitespace = True
155	n/a	option_spec = {}
156	n/a
157	n/a	def run(self):
158	n/a	node = addnodes.versionmodified()
159	n/a	node.document = self.state.document
160	n/a	node['type'] = 'deprecated-removed'
161	n/a	version = (self.arguments[0], self.arguments[1])
162	n/a	node['version'] = version
163	n/a	if len(self.arguments) == 3:
164	n/a	inodes, messages = self.state.inline_text(self.arguments[2],
165	n/a	self.lineno+1)
166	n/a	node.extend(inodes)
167	n/a	if self.content:
168	n/a	self.state.nested_parse(self.content, self.content_offset, node)
169	n/a	ret = [node] + messages
170	n/a	else:
171	n/a	ret = [node]
172	n/a	env = self.state.document.settings.env
173	n/a	env.note_versionchange('deprecated', version[0], node, self.lineno)
174	n/a	return ret
175	n/a
176	n/a
177	n/a	# Support for including Misc/NEWS
178	n/a
179	n/a	import re
180	n/a	import codecs
181	n/a
182	n/a	issue_re = re.compile('([Ii])ssue #([0-9]+)')
183	n/a	whatsnew_re = re.compile(r"(?im)^what's new in (.*?)\??$")
184	n/a
185	n/a	class MiscNews(Directive):
186	n/a	has_content = False
187	n/a	required_arguments = 1
188	n/a	optional_arguments = 0
189	n/a	final_argument_whitespace = False
190	n/a	option_spec = {}
191	n/a
192	n/a	def run(self):
193	n/a	fname = self.arguments[0]
194	n/a	source = self.state_machine.input_lines.source(
195	n/a	self.lineno - self.state_machine.input_offset - 1)
196	n/a	source_dir = path.dirname(path.abspath(source))
197	n/a	fpath = path.join(source_dir, fname)
198	n/a	self.state.document.settings.record_dependencies.add(fpath)
199	n/a	try:
200	n/a	fp = codecs.open(fpath, encoding='utf-8')
201	n/a	try:
202	n/a	content = fp.read()
203	n/a	finally:
204	n/a	fp.close()
205	n/a	except Exception:
206	n/a	text = 'The NEWS file is not available.'
207	n/a	node = nodes.strong(text, text)
208	n/a	return [node]
209	n/a	content = issue_re.sub(r'`\1ssue #\2 <http://bugs.python.org/\2>`__',
210	n/a	content)
211	n/a	content = whatsnew_re.sub(r'\1', content)
212	n/a	# remove first 3 lines as they are the main heading
213	n/a	lines = ['.. default-role:: obj', ''] + content.splitlines()[3:]
214	n/a	self.state_machine.insert_input(lines, fname)
215	n/a	return []
216	n/a
217	n/a
218	n/a	# Support for building "topic help" for pydoc
219	n/a
220	n/a	pydoc_topic_labels = [
221	n/a	'assert', 'assignment', 'atom-identifiers', 'atom-literals',
222	n/a	'attribute-access', 'attribute-references', 'augassign', 'binary',
223	n/a	'bitwise', 'bltin-code-objects', 'bltin-ellipsis-object',
224	n/a	'bltin-null-object', 'bltin-type-objects', 'booleans',
225	n/a	'break', 'callable-types', 'calls', 'class', 'comparisons', 'compound',
226	n/a	'context-managers', 'continue', 'conversions', 'customization', 'debugger',
227	n/a	'del', 'dict', 'dynamic-features', 'else', 'exceptions', 'execmodel',
228	n/a	'exprlists', 'floating', 'for', 'formatstrings', 'function', 'global',
229	n/a	'id-classes', 'identifiers', 'if', 'imaginary', 'import', 'in', 'integers',
230	n/a	'lambda', 'lists', 'naming', 'nonlocal', 'numbers', 'numeric-types',
231	n/a	'objects', 'operator-summary', 'pass', 'power', 'raise', 'return',
232	n/a	'sequence-types', 'shifting', 'slicings', 'specialattrs', 'specialnames',
233	n/a	'string-methods', 'strings', 'subscriptions', 'truth', 'try', 'types',
234	n/a	'typesfunctions', 'typesmapping', 'typesmethods', 'typesmodules',
235	n/a	'typesseq', 'typesseq-mutable', 'unary', 'while', 'with', 'yield'
236	n/a	]
237	n/a
238	n/a	from os import path
239	n/a	from time import asctime
240	n/a	from pprint import pformat
241	n/a	from docutils.io import StringOutput
242	n/a	from docutils.utils import new_document
243	n/a
244	n/a	from sphinx.builders import Builder
245	n/a	from sphinx.writers.text import TextWriter
246	n/a
247	n/a
248	n/a	class PydocTopicsBuilder(Builder):
249	n/a	name = 'pydoc-topics'
250	n/a
251	n/a	def init(self):
252	n/a	self.topics = {}
253	n/a
254	n/a	def get_outdated_docs(self):
255	n/a	return 'all pydoc topics'
256	n/a
257	n/a	def get_target_uri(self, docname, typ=None):
258	n/a	return '' # no URIs
259	n/a
260	n/a	def write(self, *ignored):
261	n/a	writer = TextWriter(self)
262	n/a	for label in self.status_iterator(pydoc_topic_labels,
263	n/a	'building topics... ',
264	n/a	length=len(pydoc_topic_labels)):
265	n/a	if label not in self.env.domaindata['std']['labels']:
266	n/a	self.warn('label %r not in documentation' % label)
267	n/a	continue
268	n/a	docname, labelid, sectname = self.env.domaindata['std']['labels'][label]
269	n/a	doctree = self.env.get_and_resolve_doctree(docname, self)
270	n/a	document = new_document('<section node>')
271	n/a	document.append(doctree.ids[labelid])
272	n/a	destination = StringOutput(encoding='utf-8')
273	n/a	writer.write(document, destination)
274	n/a	self.topics[label] = writer.output.encode('utf-8')
275	n/a
276	n/a	def finish(self):
277	n/a	f = open(path.join(self.outdir, 'topics.py'), 'w')
278	n/a	try:
279	n/a	f.write('# -- coding: utf-8 --\n')
280	n/a	f.write('# Autogenerated by Sphinx on %s\n' % asctime())
281	n/a	f.write('topics = ' + pformat(self.topics) + '\n')
282	n/a	finally:
283	n/a	f.close()
284	n/a
285	n/a
286	n/a	# Support for checking for suspicious markup
287	n/a
288	n/a	import suspicious
289	n/a
290	n/a
291	n/a	# Support for documenting Opcodes
292	n/a
293	n/a	import re
294	n/a
295	n/a	opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s$(.)$)?')
296	n/a
297	n/a	def parse_opcode_signature(env, sig, signode):
298	n/a	"""Transform an opcode signature into RST nodes."""
299	n/a	m = opcode_sig_re.match(sig)
300	n/a	if m is None:
301	n/a	raise ValueError
302	n/a	opname, arglist = m.groups()
303	n/a	signode += addnodes.desc_name(opname, opname)
304	n/a	if arglist is not None:
305	n/a	paramlist = addnodes.desc_parameterlist()
306	n/a	signode += paramlist
307	n/a	paramlist += addnodes.desc_parameter(arglist, arglist)
308	n/a	return opname.strip()
309	n/a
310	n/a
311	n/a	# Support for documenting pdb commands
312	n/a
313	n/a	pdbcmd_sig_re = re.compile(r'([a-z()!]+)\s(.)')
314	n/a
315	n/a	# later...
316	n/a	#pdbargs_tokens_re = re.compile(r'''[a-zA-Z]+ \| # identifiers
317	n/a	# [.,:]+ \| # punctuation
318	n/a	# [\[\]()] \| # parens
319	n/a	# \s+ # whitespace
320	n/a	# ''', re.X)
321	n/a
322	n/a	def parse_pdb_command(env, sig, signode):
323	n/a	"""Transform a pdb command signature into RST nodes."""
324	n/a	m = pdbcmd_sig_re.match(sig)
325	n/a	if m is None:
326	n/a	raise ValueError
327	n/a	name, args = m.groups()
328	n/a	fullname = name.replace('(', '').replace(')', '')
329	n/a	signode += addnodes.desc_name(name, name)
330	n/a	if args:
331	n/a	signode += addnodes.desc_addname(' '+args, ' '+args)
332	n/a	return fullname
333	n/a
334	n/a
335	n/a	def setup(app):
336	n/a	app.add_role('issue', issue_role)
337	n/a	app.add_role('source', source_role)
338	n/a	app.add_directive('impl-detail', ImplementationDetail)
339	n/a	app.add_directive('deprecated-removed', DeprecatedRemoved)
340	n/a	app.add_builder(PydocTopicsBuilder)
341	n/a	app.add_builder(suspicious.CheckSuspiciousMarkupBuilder)
342	n/a	app.add_description_unit('opcode', 'opcode', '%s (opcode)',
343	n/a	parse_opcode_signature)
344	n/a	app.add_description_unit('pdbcommand', 'pdbcmd', '%s (pdb command)',
345	n/a	parse_pdb_command)
346	n/a	app.add_description_unit('2to3fixer', '2to3fixer', '%s (2to3 fixer)')
347	n/a	app.add_directive_to_domain('py', 'decorator', PyDecoratorFunction)
348	n/a	app.add_directive_to_domain('py', 'decoratormethod', PyDecoratorMethod)
349	n/a	app.add_directive('miscnews', MiscNews)