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

Doc/library/weakref.rst

@@ -1,4 +1,3 @@
-
 :mod:`weakref` --- Weak references
 ==================================
 
@@ -76,9 +75,10 @@ support weak references but can add support through subclassing::
 
    obj = Dict(red=1, green=2, blue=3)   # this object is weak referenceable
 
-Other built-in types such as :class:`tuple` and :class:`long` do not support
+.. impl-detail::
-weak references even when subclassed (this is an implementation detail and may
+
-be different across various Python implementations).
+   Other built-in types such as :class:`tuple` and :class:`long` do not support
+   weak references even when subclassed.
 
 Extension types can easily be made to support weak references; see
 :ref:`weakref-support`.

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)',

Doc/tools/sphinxext/static/basic.css

@@ -345,6 +345,17 @@ p.deprecated {
     background-color: #ffa
 }
 
+.impl-detail {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    padding: 7px;
+    border: 1px solid #ccc;
+}
+
+.impl-detail p {
+    margin: 0;
+}
+
 /* -- code displays --------------------------------------------------------- */
 
 pre {