[Python-checkins] r75596 - in python/trunk/Doc: library/weakref.rst tools/sphinxext/pyspecific.py tools/sphinxext/static/basic.css

[georg.brandl]

Author: georg.brandl
Date: Thu Oct 22 10:05:04 2009
New Revision: 75596

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

Modified:
   python/trunk/Doc/library/weakref.rst
   python/trunk/Doc/tools/sphinxext/pyspecific.py
   python/trunk/Doc/tools/sphinxext/static/basic.css

Modified: python/trunk/Doc/library/weakref.rst
==============================================================================
--- python/trunk/Doc/library/weakref.rst	(original)
+++ python/trunk/Doc/library/weakref.rst	Thu Oct 22 10:05:04 2009
@@ -1,4 +1,3 @@
-
 :mod:`weakref` --- Weak references
 ==================================
 
@@ -76,9 +75,10 @@
 
    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`.

Modified: python/trunk/Doc/tools/sphinxext/pyspecific.py
==============================================================================
--- python/trunk/Doc/tools/sphinxext/pyspecific.py	(original)
+++ python/trunk/Doc/tools/sphinxext/pyspecific.py	Thu Oct 22 10:05:04 2009
@@ -35,6 +35,8 @@
 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 @@
     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 @@
         finally:
             f.close()
 
+
 # Support for checking for suspicious markup
 
 import suspicious
 
+
 # Support for documenting Opcodes
 
 import re
@@ -136,6 +159,7 @@
 
 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)',

Modified: python/trunk/Doc/tools/sphinxext/static/basic.css
==============================================================================
--- python/trunk/Doc/tools/sphinxext/static/basic.css	(original)
+++ python/trunk/Doc/tools/sphinxext/static/basic.css	Thu Oct 22 10:05:04 2009
@@ -345,6 +345,17 @@
     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 {