From 08be2e2f35db853faf77cfe128569db0fb015d50 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Thu, 22 Oct 2009 08:05:04 +0000
Subject: [PATCH] Add a new directive marking up implementation details and
 start using it.

---
 Doc/library/weakref.rst              |  8 ++++----
 Doc/tools/sphinxext/pyspecific.py    | 24 ++++++++++++++++++++++++
 Doc/tools/sphinxext/static/basic.css | 11 +++++++++++
 3 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index d23e53a531..96036e99c1 100644
--- a/Doc/library/weakref.rst
+++ b/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
-weak references even when subclassed (this is an implementation detail and may
-be different across various Python implementations).
+.. impl-detail::
+
+   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`.
diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py
index 49ad940e76..bdb6c22572 100644
--- a/Doc/tools/sphinxext/pyspecific.py
+++ b/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)',
diff --git a/Doc/tools/sphinxext/static/basic.css b/Doc/tools/sphinxext/static/basic.css
index 03b0ba3424..e76eb6eef2 100644
--- a/Doc/tools/sphinxext/static/basic.css
+++ b/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 {
-- 
2.40.0