Add a new directive marking up implementation details and start using it.

Doc/tools/sphinxext/pyspecific.py

@@ -35,6 +35,8 @@ from sphinx.locale import versionlabels
 HTMLTranslator.visit_versionmodified = new_visit_versionmodified
 
 
+# Support for marking up and linking to bugs.python.org issues
+
 def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     issue = utils.unescape(text)
     text = 'issue ' + issue
@@ -42,6 +44,25 @@ def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     return [refnode], []
 
 
+# Support for marking up implementation details
+
+from sphinx.util.compat import Directive
+
+class ImplementationDetail(Directive):
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    def run(self):
+        pnode = nodes.compound(classes=['impl-detail'])
+        content = self.content
+        content[0] = '**CPython implementation detail:** ' + content[0]
+        self.state.nested_parse(content, self.content_offset, pnode)
+        return [pnode]
+
+
 # Support for building "topic help" for pydoc
 
 pydoc_topic_labels = [
@@ -110,10 +131,12 @@ class PydocTopicsBuilder(Builder):
         finally:
             f.close()
 
+
 # Support for checking for suspicious markup
 
 import suspicious
 
+
 # Support for documenting Opcodes
 
 import re
@@ -136,6 +159,7 @@ def parse_opcode_signature(env, sig, signode):
 
 def setup(app):
     app.add_role('issue', issue_role)
+    app.add_directive('impl-detail', ImplementationDetail)
     app.add_builder(PydocTopicsBuilder)
     app.add_builder(suspicious.CheckSuspiciousMarkupBuilder)
     app.add_description_unit('opcode', 'opcode', '%s (opcode)',