Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #14005 - Removed a few unneeded workarounds in the Sphinx exten…

…sion. Thanks for the report and patch, Ramiro Morales.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13447 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit cd8758ef4dd28f55858d1df65bf5d4ce07137eb1 1 parent fad4a93
Jannis Leidel authored July 25, 2010
152  docs/_ext/djangodocs.py
... ...
@@ -1,9 +1,9 @@
1 1
 """
2 2
 Sphinx plugins for Django documentation.
3 3
 """
  4
+import os
4 5
 
5  
-import docutils.nodes
6  
-import docutils.transforms
  6
+from docutils import nodes, transforms
7 7
 try:
8 8
     import json
9 9
 except ImportError:
@@ -14,26 +14,12 @@
14 14
             from django.utils import simplejson as json
15 15
         except ImportError:
16 16
             json = None
17  
-import os
18  
-import sphinx
19  
-import sphinx.addnodes
20  
-try:
21  
-    from sphinx import builders
22  
-except ImportError:
23  
-    import sphinx.builder as builders
24  
-try:
25  
-    import sphinx.builders.html as builders_html
26  
-except ImportError:
27  
-    builders_html = builders
  17
+
  18
+from sphinx import addnodes, roles
  19
+from sphinx.builders.html import StandaloneHTMLBuilder
  20
+from sphinx.writers.html import SmartyPantsHTMLTranslator
28 21
 from sphinx.util.console import bold
29  
-import sphinx.directives
30  
-import sphinx.environment
31  
-try:
32  
-    import sphinx.writers.html as sphinx_htmlwriter
33  
-except ImportError:
34  
-    import sphinx.htmlwriter as sphinx_htmlwriter
35  
-import sphinx.roles
36  
-from docutils import nodes
  22
+
37 23
 
38 24
 def setup(app):
39 25
     app.add_crossref_type(
@@ -74,24 +60,20 @@ def setup(app):
74 60
     app.add_transform(SuppressBlockquotes)
75 61
     app.add_builder(DjangoStandaloneHTMLBuilder)
76 62
 
77  
-    # Monkeypatch PickleHTMLBuilder so that it doesn't die in Sphinx 0.4.2
78  
-    if sphinx.__version__ == '0.4.2':
79  
-        monkeypatch_pickle_builder()
80  
-
81 63
 def parse_version_directive(name, arguments, options, content, lineno,
82 64
                       content_offset, block_text, state, state_machine):
83 65
     env = state.document.settings.env
84 66
     is_nextversion = env.config.django_next_version == arguments[0]
85 67
     ret = []
86  
-    node = sphinx.addnodes.versionmodified()
  68
+    node = addnodes.versionmodified()
87 69
     ret.append(node)
88 70
     if not is_nextversion:
89 71
         if len(arguments) == 1:
90 72
             linktext = 'Please, see the release notes <releases-%s>' % (arguments[0])
91 73
             try:
92  
-                xrefs = sphinx.roles.XRefRole()('ref', linktext, linktext, lineno, state) # Sphinx >= 1.0
  74
+                xrefs = roles.XRefRole()('ref', linktext, linktext, lineno, state) # Sphinx >= 1.0
93 75
             except:
94  
-                xrefs = sphinx.roles.xfileref_role('ref', linktext, linktext, lineno, state) # Sphinx < 1.0
  76
+                xrefs = roles.xfileref_role('ref', linktext, linktext, lineno, state) # Sphinx < 1.0
95 77
             node.extend(xrefs[0])
96 78
         node['version'] = arguments[0]
97 79
     else:
@@ -106,29 +88,29 @@ def parse_version_directive(name, arguments, options, content, lineno,
106 88
     env.note_versionchange(node['type'], node['version'], node, lineno)
107 89
     return ret
108 90
 
109  
-                
110  
-class SuppressBlockquotes(docutils.transforms.Transform):
  91
+
  92
+class SuppressBlockquotes(transforms.Transform):
111 93
     """
112 94
     Remove the default blockquotes that encase indented list, tables, etc.
113 95
     """
114 96
     default_priority = 300
115  
-    
  97
+
116 98
     suppress_blockquote_child_nodes = (
117  
-        docutils.nodes.bullet_list, 
118  
-        docutils.nodes.enumerated_list, 
119  
-        docutils.nodes.definition_list,
120  
-        docutils.nodes.literal_block, 
121  
-        docutils.nodes.doctest_block, 
122  
-        docutils.nodes.line_block, 
123  
-        docutils.nodes.table
  99
+        nodes.bullet_list,
  100
+        nodes.enumerated_list,
  101
+        nodes.definition_list,
  102
+        nodes.literal_block,
  103
+        nodes.doctest_block,
  104
+        nodes.line_block,
  105
+        nodes.table
124 106
     )
125  
-    
  107
+
126 108
     def apply(self):
127  
-        for node in self.document.traverse(docutils.nodes.block_quote):
  109
+        for node in self.document.traverse(nodes.block_quote):
128 110
             if len(node.children) == 1 and isinstance(node.children[0], self.suppress_blockquote_child_nodes):
129 111
                 node.replace_self(node.children[0])
130 112
 
131  
-class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator):
  113
+class DjangoHTMLTranslator(SmartyPantsHTMLTranslator):
132 114
     """
133 115
     Django-specific reST to HTML tweaks.
134 116
     """
@@ -136,42 +118,41 @@ class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator):
136 118
     # Don't use border=1, which docutils does by default.
137 119
     def visit_table(self, node):
138 120
         self.body.append(self.starttag(node, 'table', CLASS='docutils'))
139  
-    
  121
+
140 122
     # <big>? Really?
141 123
     def visit_desc_parameterlist(self, node):
142 124
         self.body.append('(')
143 125
         self.first_param = 1
144  
-    
  126
+
145 127
     def depart_desc_parameterlist(self, node):
146 128
         self.body.append(')')
147  
-        pass
148  
-        
  129
+
149 130
     #
150 131
     # Don't apply smartypants to literal blocks
151 132
     #
152 133
     def visit_literal_block(self, node):
153 134
         self.no_smarty += 1
154  
-        sphinx_htmlwriter.SmartyPantsHTMLTranslator.visit_literal_block(self, node)
  135
+        SmartyPantsHTMLTranslator.visit_literal_block(self, node)
155 136
 
156 137
     def depart_literal_block(self, node):
157  
-        sphinx_htmlwriter.SmartyPantsHTMLTranslator.depart_literal_block(self, node)
  138
+        SmartyPantsHTMLTranslator.depart_literal_block(self, node)
158 139
         self.no_smarty -= 1
159  
-        
  140
+
160 141
     #
161  
-    # Turn the "new in version" stuff (versoinadded/versionchanged) into a
  142
+    # Turn the "new in version" stuff (versionadded/versionchanged) into a
162 143
     # better callout -- the Sphinx default is just a little span,
163 144
     # which is a bit less obvious that I'd like.
164 145
     #
165 146
     # FIXME: these messages are all hardcoded in English. We need to change
166 147
     # that to accomodate other language docs, but I can't work out how to make
167  
-    # that work and I think it'll require Sphinx 0.5 anyway.
  148
+    # that work.
168 149
     #
169 150
     version_text = {
170 151
         'deprecated':       'Deprecated in Django %s',
171 152
         'versionchanged':   'Changed in Django %s',
172 153
         'versionadded':     'New in Django %s',
173 154
     }
174  
-    
  155
+
175 156
     def visit_versionmodified(self, node):
176 157
         self.body.append(
177 158
             self.starttag(node, 'div', CLASS=node['type'])
@@ -181,40 +162,27 @@ def visit_versionmodified(self, node):
181 162
             len(node) and ":" or "."
182 163
         )
183 164
         self.body.append('<span class="title">%s</span> ' % title)
184  
-    
  165
+
185 166
     def depart_versionmodified(self, node):
186 167
         self.body.append("</div>\n")
187  
-    
188  
-    # Give each section a unique ID -- nice for custom CSS hooks
189  
-    # This is different on docutils 0.5 vs. 0.4...
190  
-
191  
-    if hasattr(sphinx_htmlwriter.SmartyPantsHTMLTranslator, 'start_tag_with_title') and sphinx.__version__ == '0.4.2':
192  
-        def start_tag_with_title(self, node, tagname, **atts):
193  
-            node = {
194  
-                'classes': node.get('classes', []), 
195  
-                'ids': ['s-%s' % i for i in node.get('ids', [])]
196  
-            }
197  
-            return self.starttag(node, tagname, **atts)
198 168
 
199  
-    else:
200  
-        def visit_section(self, node):
201  
-            old_ids = node.get('ids', [])
202  
-            node['ids'] = ['s-' + i for i in old_ids]
203  
-            if sphinx.__version__ != '0.4.2':
204  
-                node['ids'].extend(old_ids)
205  
-            sphinx_htmlwriter.SmartyPantsHTMLTranslator.visit_section(self, node)
206  
-            node['ids'] = old_ids
  169
+    # Give each section a unique ID -- nice for custom CSS hooks
  170
+    def visit_section(self, node):
  171
+        old_ids = node.get('ids', [])
  172
+        node['ids'] = ['s-' + i for i in old_ids]
  173
+        node['ids'].extend(old_ids)
  174
+        SmartyPantsHTMLTranslator.visit_section(self, node)
  175
+        node['ids'] = old_ids
207 176
 
208 177
 def parse_django_admin_node(env, sig, signode):
209 178
     command = sig.split(' ')[0]
210 179
     env._django_curr_admin_command = command
211 180
     title = "django-admin.py %s" % sig
212  
-    signode += sphinx.addnodes.desc_name(title, title)
  181
+    signode += addnodes.desc_name(title, title)
213 182
     return sig
214 183
 
215 184
 def parse_django_adminopt_node(env, sig, signode):
216 185
     """A copy of sphinx.directives.CmdoptionDesc.parse_signature()"""
217  
-    from sphinx import addnodes
218 186
     try:
219 187
         from sphinx.domains.std import option_desc_re # Sphinx >= 1.0
220 188
     except:
@@ -234,44 +202,8 @@ def parse_django_adminopt_node(env, sig, signode):
234 202
         raise ValueError
235 203
     return firstname
236 204
 
237  
-def monkeypatch_pickle_builder():
238  
-    import shutil
239  
-    from os import path
240  
-    try:
241  
-        import cPickle as pickle
242  
-    except ImportError:
243  
-        import pickle
244  
-    
245  
-    def handle_finish(self):
246  
-        # dump the global context
247  
-        outfilename = path.join(self.outdir, 'globalcontext.pickle')
248  
-        f = open(outfilename, 'wb')
249  
-        try:
250  
-            pickle.dump(self.globalcontext, f, 2)
251  
-        finally:
252  
-            f.close()
253  
-
254  
-        self.info(bold('dumping search index...'))
255  
-        self.indexer.prune(self.env.all_docs)
256  
-        f = open(path.join(self.outdir, 'searchindex.pickle'), 'wb')
257  
-        try:
258  
-            self.indexer.dump(f, 'pickle')
259  
-        finally:
260  
-            f.close()
261  
-
262  
-        # copy the environment file from the doctree dir to the output dir
263  
-        # as needed by the web app
264  
-        shutil.copyfile(path.join(self.doctreedir, builders.ENV_PICKLE_FILENAME),
265  
-                        path.join(self.outdir, builders.ENV_PICKLE_FILENAME))
266  
-
267  
-        # touch 'last build' file, used by the web application to determine
268  
-        # when to reload its environment and clear the cache
269  
-        open(path.join(self.outdir, builders.LAST_BUILD_FILENAME), 'w').close()
270  
-
271  
-    builders.PickleHTMLBuilder.handle_finish = handle_finish
272  
-
273 205
 
274  
-class DjangoStandaloneHTMLBuilder(builders_html.StandaloneHTMLBuilder):
  206
+class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder):
275 207
     """
276 208
     Subclass to add some extra things we need.
277 209
     """
2  docs/conf.py
@@ -29,7 +29,7 @@
29 29
 extensions = ["djangodocs"]
30 30
 
31 31
 # Add any paths that contain templates here, relative to this directory.
32  
-templates_path = ["_templates"]
  32
+# templates_path = []
33 33
 
34 34
 # The suffix of source filenames.
35 35
 source_suffix = '.txt'
5  docs/internals/documentation.txt
@@ -15,6 +15,11 @@ __ http://docutils.sourceforge.net/
15 15
 To actually build the documentation locally, you'll currently need to install
16 16
 Sphinx -- ``easy_install Sphinx`` should do the trick.
17 17
 
  18
+.. note::
  19
+
  20
+    Generation of the Django documentation will work with Sphinx version 0.6
  21
+    or newer, but we recommend going straigh to Sphinx 1.0 or newer.
  22
+
18 23
 Then, building the html is easy; just ``make html`` from the ``docs`` directory.
19 24
 
20 25
 To get started contributing, you'll want to read the `ReStructuredText

0 notes on commit cd8758e

Please sign in to comment.
Something went wrong with that request. Please try again.