diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index a17406ae1a2..9b5a5e3849c 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -9,15 +9,32 @@ :license: Python license. """ -ISSUE_URI = 'https://bugs.python.org/issue%s' -SOURCE_URI = 'https://hg.python.org/cpython/file/3.4/%s' +import re +import codecs +from os import path +from time import asctime +from pprint import pformat +from docutils.io import StringOutput +from docutils.utils import new_document from docutils import nodes, utils +from sphinx import addnodes +from sphinx.builders import Builder from sphinx.util.nodes import split_explicit_title from sphinx.util.compat import Directive from sphinx.writers.html import HTMLTranslator +from sphinx.writers.text import TextWriter from sphinx.writers.latex import LaTeXTranslator +from sphinx.domains.python import PyModulelevel, PyClassmember + +# Support for checking for suspicious markup + +import suspicious + + +ISSUE_URI = 'https://bugs.python.org/issue%s' +SOURCE_URI = 'https://hg.python.org/cpython/file/3.4/%s' # monkey-patch reST parser to disable alphabetic and roman enumerated lists from docutils.parsers.rst.states import Body @@ -29,6 +46,9 @@ Body.enum.converters['loweralpha'] = \ # monkey-patch HTML and LaTeX translators to keep doctest blocks in the # doctest docs themselves orig_visit_literal_block = HTMLTranslator.visit_literal_block +orig_depart_literal_block = LaTeXTranslator.depart_literal_block + + def new_visit_literal_block(self, node): meta = self.builder.env.metadata[self.builder.current_docname] old_trim_doctest_flags = self.highlighter.trim_doctest_flags @@ -39,9 +59,7 @@ def new_visit_literal_block(self, node): finally: self.highlighter.trim_doctest_flags = old_trim_doctest_flags -HTMLTranslator.visit_literal_block = new_visit_literal_block -orig_depart_literal_block = LaTeXTranslator.depart_literal_block def new_depart_literal_block(self, node): meta = self.builder.env.metadata[self.curfilestack[-1]] old_trim_doctest_flags = self.highlighter.trim_doctest_flags @@ -52,8 +70,11 @@ def new_depart_literal_block(self, node): finally: self.highlighter.trim_doctest_flags = old_trim_doctest_flags + +HTMLTranslator.visit_literal_block = new_visit_literal_block LaTeXTranslator.depart_literal_block = new_depart_literal_block + # Support for marking up and linking to bugs.python.org issues def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): @@ -101,9 +122,6 @@ class ImplementationDetail(Directive): # Support for documenting decorators -from sphinx import addnodes -from sphinx.domains.python import PyModulelevel, PyClassmember - class PyDecoratorMixin(object): def handle_signature(self, sig, signode): ret = super(PyDecoratorMixin, self).handle_signature(sig, signode) @@ -113,12 +131,14 @@ class PyDecoratorMixin(object): def needs_arglist(self): return False + class PyDecoratorFunction(PyDecoratorMixin, PyModulelevel): def run(self): # a decorator function is a function after all self.name = 'py:function' return PyModulelevel.run(self) + class PyDecoratorMethod(PyDecoratorMixin, PyClassmember): def run(self): self.name = 'py:method' @@ -162,7 +182,8 @@ class DeprecatedRemoved(Directive): classes=['versionmodified'])) else: para = nodes.paragraph('', '', - nodes.inline('', '%s.' % text, classes=['versionmodified'])) + nodes.inline('', '%s.' % text, + classes=['versionmodified'])) if len(node): node.insert(0, para) else: @@ -174,12 +195,10 @@ class DeprecatedRemoved(Directive): # Support for including Misc/NEWS -import re -import codecs - issue_re = re.compile('([Ii])ssue #([0-9]+)') whatsnew_re = re.compile(r"(?im)^what's new in (.*?)\??$") + class MiscNews(Directive): has_content = False required_arguments = 1 @@ -233,15 +252,6 @@ pydoc_topic_labels = [ 'typesseq', 'typesseq-mutable', 'unary', 'while', 'with', 'yield' ] -from os import path -from time import asctime -from pprint import pformat -from docutils.io import StringOutput -from docutils.utils import new_document - -from sphinx.builders import Builder -from sphinx.writers.text import TextWriter - class PydocTopicsBuilder(Builder): name = 'pydoc-topics' @@ -281,17 +291,11 @@ class PydocTopicsBuilder(Builder): f.close() -# Support for checking for suspicious markup - -import suspicious - - # Support for documenting Opcodes -import re - opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s*\((.*)\))?') + def parse_opcode_signature(env, sig, signode): """Transform an opcode signature into RST nodes.""" m = opcode_sig_re.match(sig) @@ -311,12 +315,13 @@ def parse_opcode_signature(env, sig, signode): pdbcmd_sig_re = re.compile(r'([a-z()!]+)\s*(.*)') # later... -#pdbargs_tokens_re = re.compile(r'''[a-zA-Z]+ | # identifiers +# pdbargs_tokens_re = re.compile(r'''[a-zA-Z]+ | # identifiers # [.,:]+ | # punctuation # [\[\]()] | # parens # \s+ # whitespace # ''', re.X) + def parse_pdb_command(env, sig, signode): """Transform a pdb command signature into RST nodes.""" m = pdbcmd_sig_re.match(sig)