merge with 3.4

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/default/%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/default/%s'
 
 # monkey-patch reST parser to disable alphabetic and roman enumerated lists
 from docutils.parsers.rst.states import Body
@@ -29,6 +46,9 @@
 # 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 @@ def run(self):
 
 # 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 @@ def handle_signature(self, sig, signode):
     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 @@ def run(self):
                                                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 @@ def run(self):
 
 # 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 @@ def run(self):
     '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 @@ def finish(self):
             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)