Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #13616 - Updated the documentation to be compatible with Sphinx…

… 1.0.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13446 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit fad4a93275a6a5267912c9fc88cdeee44dd5572f 1 parent aaa5dfb
Jannis Leidel authored July 24, 2010
67  docs/Makefile
@@ -12,20 +12,26 @@ PAPEROPT_a4     = -D latex_paper_size=a4
12 12
 PAPEROPT_letter = -D latex_paper_size=letter
13 13
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14 14
 
15  
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
  15
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
16 16
 
17 17
 help:
18 18
 	@echo "Please use \`make <target>' where <target> is one of"
19  
-	@echo "  html      to make standalone HTML files"
20  
-	@echo "  dirhtml   to make HTML files named index.html in directories"
21  
-	@echo "  pickle    to make pickle files"
22  
-	@echo "  json      to make JSON files"
23  
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
24  
-	@echo "  qthelp    to make HTML files and a qthelp project"
25  
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
26  
-	@echo "  changes   to make an overview of all changed/added/deprecated items"
27  
-	@echo "  linkcheck to check all external links for integrity"
28  
-	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
  19
+	@echo "  html       to make standalone HTML files"
  20
+	@echo "  dirhtml    to make HTML files named index.html in directories"
  21
+	@echo "  singlehtml to make a single large HTML file"
  22
+	@echo "  pickle     to make pickle files"
  23
+	@echo "  json       to make JSON files"
  24
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
  25
+	@echo "  qthelp     to make HTML files and a qthelp project"
  26
+	@echo "  devhelp    to make HTML files and a Devhelp project"
  27
+	@echo "  epub       to make an epub"
  28
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
  29
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
  30
+	@echo "  text       to make text files"
  31
+	@echo "  man        to make manual pages"
  32
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
  33
+	@echo "  linkcheck  to check all external links for integrity"
  34
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
29 35
 
30 36
 clean:
31 37
 	-rm -rf $(BUILDDIR)/*
@@ -40,6 +46,11 @@ dirhtml:
40 46
 	@echo
41 47
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
42 48
 
  49
+singlehtml:
  50
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
  51
+	@echo
  52
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
  53
+
43 54
 pickle:
44 55
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
45 56
 	@echo
@@ -65,12 +76,42 @@ qthelp:
65 76
 	@echo "To view the help file:"
66 77
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django.qhc"
67 78
 
  79
+devhelp:
  80
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
  81
+	@echo
  82
+	@echo "Build finished."
  83
+	@echo "To view the help file:"
  84
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/django"
  85
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django"
  86
+	@echo "# devhelp"
  87
+
  88
+epub:
  89
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
  90
+	@echo
  91
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
  92
+
68 93
 latex:
69 94
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
70 95
 	@echo
71 96
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
72  
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
73  
-	      "run these through (pdf)latex."
  97
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
  98
+	      "(use \`make latexpdf' here to do that automatically)."
  99
+
  100
+latexpdf:
  101
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
  102
+	@echo "Running LaTeX files through pdflatex..."
  103
+	make -C $(BUILDDIR)/latex all-pdf
  104
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
  105
+
  106
+text:
  107
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
  108
+	@echo
  109
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
  110
+
  111
+man:
  112
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
  113
+	@echo
  114
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
74 115
 
75 116
 changes:
76 117
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
23  docs/_ext/djangodocs.py
@@ -88,7 +88,10 @@ def parse_version_directive(name, arguments, options, content, lineno,
88 88
     if not is_nextversion:
89 89
         if len(arguments) == 1:
90 90
             linktext = 'Please, see the release notes <releases-%s>' % (arguments[0])
91  
-            xrefs = sphinx.roles.xfileref_role('ref', linktext, linktext, lineno, state)
  91
+            try:
  92
+                xrefs = sphinx.roles.XRefRole()('ref', linktext, linktext, lineno, state) # Sphinx >= 1.0
  93
+            except:
  94
+                xrefs = sphinx.roles.xfileref_role('ref', linktext, linktext, lineno, state) # Sphinx < 1.0
92 95
             node.extend(xrefs[0])
93 96
         node['version'] = arguments[0]
94 97
     else:
@@ -159,7 +162,7 @@ def depart_literal_block(self, node):
159 162
     # better callout -- the Sphinx default is just a little span,
160 163
     # which is a bit less obvious that I'd like.
161 164
     #
162  
-    # FIXME: these messages are all hardcoded in English. We need to chanage 
  165
+    # FIXME: these messages are all hardcoded in English. We need to change
163 166
     # that to accomodate other language docs, but I can't work out how to make
164 167
     # that work and I think it'll require Sphinx 0.5 anyway.
165 168
     #
@@ -212,7 +215,10 @@ def parse_django_admin_node(env, sig, signode):
212 215
 def parse_django_adminopt_node(env, sig, signode):
213 216
     """A copy of sphinx.directives.CmdoptionDesc.parse_signature()"""
214 217
     from sphinx import addnodes
215  
-    from sphinx.directives.desc import option_desc_re
  218
+    try:
  219
+        from sphinx.domains.std import option_desc_re # Sphinx >= 1.0
  220
+    except:
  221
+        from sphinx.directives.desc import option_desc_re # Sphinx < 1.0
216 222
     count = 0
217 223
     firstname = ''
218 224
     for m in option_desc_re.finditer(sig):
@@ -278,9 +284,14 @@ def finish(self):
278 284
             self.warn("cannot create templatebuiltins.js due to missing simplejson dependency")
279 285
             return
280 286
         self.info(bold("writing templatebuiltins.js..."))
281  
-        xrefs = self.env.reftargets.keys()
282  
-        templatebuiltins = dict([('ttags', [n for (t,n) in xrefs if t == 'ttag']),
283  
-                                 ('tfilters', [n for (t,n) in xrefs if t == 'tfilter'])])
  287
+        try:
  288
+            xrefs = self.env.reftargets.keys()
  289
+            templatebuiltins = dict([('ttags', [n for (t,n) in xrefs if t == 'ttag']),
  290
+                                     ('tfilters', [n for (t,n) in xrefs if t == 'tfilter'])])
  291
+        except AttributeError:
  292
+            xrefs = self.env.domaindata["std"]["objects"]
  293
+            templatebuiltins = dict([('ttags', [n for (t,n) in xrefs if t == 'templatetag']),
  294
+                                     ('tfilters', [n for (t,n) in xrefs if t == 'templatefilter'])])
284 295
         outfilename = os.path.join(self.outdir, "templatebuiltins.js")
285 296
         f = open(outfilename, 'wb')
286 297
         f.write('var django_template_builtins = ')
4  docs/_templates/genindex.html
... ...
@@ -1,4 +0,0 @@
1  
-{% extends "!genindex.html" %}
2  
-
3  
-{% block bodyclass %}{% endblock %}
4  
-{% block sidebarwrapper %}{% endblock %}
3  docs/_templates/modindex.html
... ...
@@ -1,3 +0,0 @@
1  
-{% extends "!modindex.html" %}
2  
-{% block bodyclass %}{% endblock %}
3  
-{% block sidebarwrapper %}{% endblock %}
3  docs/_templates/search.html
... ...
@@ -1,3 +0,0 @@
1  
-{% extends "!search.html" %}
2  
-{% block bodyclass %}{% endblock %}
3  
-{% block sidebarwrapper %}{% endblock %}
4  docs/_theme/djangodocs/genindex.html
... ...
@@ -0,0 +1,4 @@
  1
+{% extends "basic/genindex.html" %}
  2
+
  3
+{% block bodyclass %}{% endblock %}
  4
+{% block sidebarwrapper %}{% endblock %}
4  docs/_templates/layout.html → docs/_theme/djangodocs/layout.html
... ...
@@ -1,4 +1,4 @@
1  
-{% extends "!layout.html" %}
  1
+{% extends "basic/layout.html" %}
2 2
 
3 3
 {%- macro secondnav() %}
4 4
   {%- if prev %}
@@ -61,7 +61,7 @@
61 61
         <a title="Home page" href="{{ pathto('index') }}">Home</a> {{ reldelim2 }}
62 62
         <a title="Table of contents" href="{{ pathto('contents') }}">Table of contents</a> {{ reldelim2 }}
63 63
         <a title="Global index" href="{{ pathto('genindex') }}">Index</a> {{ reldelim2 }}
64  
-        <a title="Module index" href="{{ pathto('modindex') }}">Modules</a>
  64
+        <a title="Module index" href="{{ pathto('py-modindex') }}">Modules</a>
65 65
       </div>
66 66
       <div class="nav">{{ secondnav() }}</div>
67 67
     </div>
3  docs/_theme/djangodocs/modindex.html
... ...
@@ -0,0 +1,3 @@
  1
+{% extends "basic/modindex.html" %}
  2
+{% block bodyclass %}{% endblock %}
  3
+{% block sidebarwrapper %}{% endblock %}
3  docs/_theme/djangodocs/search.html
... ...
@@ -0,0 +1,3 @@
  1
+{% extends "basic/search.html" %}
  2
+{% block bodyclass %}{% endblock %}
  3
+{% block sidebarwrapper %}{% endblock %}
0  docs/_static/default.css → docs/_theme/djangodocs/static/default.css
File renamed without changes
0  docs/_static/djangodocs.css → docs/_theme/djangodocs/static/djangodocs.css
File renamed without changes
0  docs/_static/docicons-behindscenes.png → ...theme/djangodocs/static/docicons-behindscenes.png
File renamed without changes
0  docs/_static/docicons-note.png → docs/_theme/djangodocs/static/docicons-note.png
File renamed without changes
0  docs/_static/docicons-philosophy.png → .../_theme/djangodocs/static/docicons-philosophy.png
File renamed without changes
0  docs/_static/homepage.css → docs/_theme/djangodocs/static/homepage.css
File renamed without changes
0  docs/_static/reset-fonts-grids.css → docs/_theme/djangodocs/static/reset-fonts-grids.css
File renamed without changes
4  docs/_theme/djangodocs/theme.conf
... ...
@@ -0,0 +1,4 @@
  1
+[theme]
  2
+inherit = basic
  3
+stylesheet = default.css
  4
+pygments_style = trac
172  docs/conf.py
@@ -8,17 +8,21 @@
8 8
 # The contents of this file are pickled, so don't put values in the namespace
9 9
 # that aren't pickleable (module imports are okay, they're removed automatically).
10 10
 #
11  
-# All configuration values have a default value; values that are commented out
12  
-# serve to show the default value.
  11
+# All configuration values have a default; values that are commented out
  12
+# serve to show the default.
13 13
 
14 14
 import sys
15 15
 import os
16 16
 
17  
-# If your extensions are in another directory, add it here.
18  
-sys.path.append(os.path.join(os.path.dirname(__file__), "_ext"))
  17
+# If extensions (or modules to document with autodoc) are in another directory,
  18
+# add these directories to sys.path here. If the directory is relative to the
  19
+# documentation root, use os.path.abspath to make it absolute, like shown here.
  20
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext")))
19 21
 
20  
-# General configuration
21  
-# ---------------------
  22
+# -- General configuration -----------------------------------------------------
  23
+
  24
+# If your documentation needs a minimal Sphinx version, state it here.
  25
+#needs_sphinx = '1.0'
22 26
 
23 27
 # Add any Sphinx extension module names here, as strings. They can be extensions
24 28
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -30,6 +34,9 @@
30 34
 # The suffix of source filenames.
31 35
 source_suffix = '.txt'
32 36
 
  37
+# The encoding of source files.
  38
+#source_encoding = 'utf-8-sig'
  39
+
33 40
 # The master toctree document.
34 41
 master_doc = 'contents'
35 42
 
@@ -37,8 +44,10 @@
37 44
 project = 'Django'
38 45
 copyright = 'Django Software Foundation and contributors'
39 46
 
40  
-# The default replacements for |version| and |release|, also used in various
41  
-# other places throughout the built documents.
  47
+
  48
+# The version info for the project you're documenting, acts as replacement for
  49
+# |version| and |release|, also used in various other places throughout the
  50
+# built documents.
42 51
 #
43 52
 # The short X.Y version.
44 53
 version = '1.2'
@@ -47,14 +56,22 @@
47 56
 # The next version to be released
48 57
 django_next_version = '1.3'
49 58
 
  59
+# The language for content autogenerated by Sphinx. Refer to documentation
  60
+# for a list of supported languages.
  61
+#language = None
  62
+
50 63
 # There are two options for replacing |today|: either, you set today to some
51 64
 # non-false value, then it is used:
52 65
 #today = ''
53 66
 # Else, today_fmt is used as the format for a strftime call.
54 67
 today_fmt = '%B %d, %Y'
55 68
 
56  
-# List of documents that shouldn't be included in the build.
57  
-#unused_docs = []
  69
+# List of patterns, relative to source directory, that match files and
  70
+# directories to ignore when looking for source files.
  71
+exclude_patterns = ['_build']
  72
+
  73
+# The reST default role (used for this markup: `text`) to use for all documents.
  74
+#default_role = None
58 75
 
59 76
 # If true, '()' will be appended to :func: etc. cross-reference text.
60 77
 add_function_parentheses = True
@@ -75,13 +92,35 @@
75 92
 # Note: exclude_dirnames is new in Sphinx 0.5 
76 93
 exclude_dirnames = ['.svn']
77 94
 
78  
-# Options for HTML output
79  
-# -----------------------
  95
+# -- Options for HTML output ---------------------------------------------------
  96
+
  97
+# The theme to use for HTML and HTML Help pages.  See the documentation for
  98
+# a list of builtin themes.
  99
+html_theme = "djangodocs"
  100
+
  101
+# Theme options are theme-specific and customize the look and feel of a theme
  102
+# further.  For a list of options available for each theme, see the
  103
+# documentation.
  104
+#html_theme_options = {}
  105
+
  106
+# Add any paths that contain custom themes here, relative to this directory.
  107
+html_theme_path = ["_theme"]
  108
+
  109
+# The name for this set of Sphinx documents.  If None, it defaults to
  110
+# "<project> v<release> documentation".
  111
+#html_title = None
  112
+
  113
+# A shorter title for the navigation bar.  Default is the same as html_title.
  114
+#html_short_title = None
80 115
 
81  
-# The style sheet to use for HTML and HTML Help pages. A file of that name
82  
-# must exist either in Sphinx' static/ path, or in one of the custom paths
83  
-# given in html_static_path.
84  
-html_style = 'default.css'
  116
+# The name of an image file (relative to this directory) to place at the top
  117
+# of the sidebar.
  118
+#html_logo = None
  119
+
  120
+# The name of an image file (within the static path) to use as favicon of the
  121
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
  122
+# pixels large.
  123
+#html_favicon = None
85 124
 
86 125
 # Add any paths that contain custom static files (such as style sheets) here,
87 126
 # relative to this directory. They are copied after the builtin static files,
@@ -110,17 +149,38 @@
110 149
 html_additional_pages = {}
111 150
 
112 151
 # If false, no module index is generated.
113  
-#html_use_modindex = True
  152
+#html_domain_indices = True
  153
+
  154
+# If false, no index is generated.
  155
+#html_use_index = True
  156
+
  157
+# If true, the index is split into individual pages for each letter.
  158
+#html_split_index = False
  159
+
  160
+# If true, links to the reST sources are added to the pages.
  161
+#html_show_sourcelink = True
  162
+
  163
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
  164
+#html_show_sphinx = True
114 165
 
115  
-# If true, the reST sources are included in the HTML build as _sources/<name>.
116  
-html_copy_source = True
  166
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
  167
+#html_show_copyright = True
  168
+
  169
+# If true, an OpenSearch description file will be output, and all pages will
  170
+# contain a <link> tag referring to it.  The value of this option must be the
  171
+# base URL from which the finished HTML is served.
  172
+#html_use_opensearch = ''
  173
+
  174
+# This is the file name suffix for HTML files (e.g. ".xhtml").
  175
+#html_file_suffix = None
117 176
 
118 177
 # Output file base name for HTML help builder.
119 178
 htmlhelp_basename = 'Djangodoc'
120 179
 
  180
+modindex_common_prefix = ["django."]
  181
+
121 182
 
122  
-# Options for LaTeX output
123  
-# ------------------------
  183
+# -- Options for LaTeX output --------------------------------------------------
124 184
 
125 185
 # The paper size ('letter' or 'a4').
126 186
 #latex_paper_size = 'letter'
@@ -132,9 +192,24 @@
132 192
 # (source start file, target name, title, author, document class [howto/manual]).
133 193
 #latex_documents = []
134 194
 latex_documents = [
135  
-  ('contents', 'django.tex', 'Django Documentation', 'Django Software Foundation', 'manual'),
  195
+  ('contents', 'django.tex', u'Django Documentation',
  196
+   u'Django Software Foundation', 'manual'),
136 197
 ]
137 198
 
  199
+# The name of an image file (relative to this directory) to place at the top of
  200
+# the title page.
  201
+#latex_logo = None
  202
+
  203
+# For "manual" documents, if this is true, then toplevel headings are parts,
  204
+# not chapters.
  205
+#latex_use_parts = False
  206
+
  207
+# If true, show page references after internal links.
  208
+#latex_show_pagerefs = False
  209
+
  210
+# If true, show URL addresses after external links.
  211
+#latex_show_urls = False
  212
+
138 213
 # Additional stuff for the LaTeX preamble.
139 214
 #latex_preamble = ''
140 215
 
@@ -142,10 +217,53 @@
142 217
 #latex_appendices = []
143 218
 
144 219
 # If false, no module index is generated.
145  
-#latex_use_modindex = True
  220
+#latex_domain_indices = True
146 221
 
147  
-# For "manual" documents, if this is true, then toplevel headings are parts,
148  
-# not chapters.
149  
-# If this isn't set to True, the LaTex writer can only handle six levels of headers.
150  
-latex_use_parts = True
151 222
 
  223
+# -- Options for manual page output --------------------------------------------
  224
+
  225
+# One entry per manual page. List of tuples
  226
+# (source start file, name, description, authors, manual section).
  227
+man_pages = [
  228
+    ('contents', 'django', 'Django Documentation', ['Django Software Foundation'], 1)
  229
+]
  230
+
  231
+
  232
+# -- Options for Epub output ---------------------------------------------------
  233
+
  234
+# Bibliographic Dublin Core info.
  235
+epub_title = u'Django'
  236
+epub_author = u'Django Software Foundation'
  237
+epub_publisher = u'Django Software Foundation'
  238
+epub_copyright = u'2010, Django Software Foundation'
  239
+
  240
+# The language of the text. It defaults to the language option
  241
+# or en if the language is not set.
  242
+#epub_language = ''
  243
+
  244
+# The scheme of the identifier. Typical schemes are ISBN or URL.
  245
+#epub_scheme = ''
  246
+
  247
+# The unique identifier of the text. This can be a ISBN number
  248
+# or the project homepage.
  249
+#epub_identifier = ''
  250
+
  251
+# A unique identification for the text.
  252
+#epub_uid = ''
  253
+
  254
+# HTML files that should be inserted before the pages created by sphinx.
  255
+# The format is a list of tuples containing the path and title.
  256
+#epub_pre_files = []
  257
+
  258
+# HTML files shat should be inserted after the pages created by sphinx.
  259
+# The format is a list of tuples containing the path and title.
  260
+#epub_post_files = []
  261
+
  262
+# A list of files that should not be packed into the epub file.
  263
+#epub_exclude_files = []
  264
+
  265
+# The depth of the table of contents in toc.ncx.
  266
+#epub_tocdepth = 3
  267
+
  268
+# Allow duplicate toc entries.
  269
+#epub_tocdup = True

0 notes on commit fad4a93

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