From fad4a93275a6a5267912c9fc88cdeee44dd5572f Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Sat, 24 Jul 2010 10:21:21 +0000 Subject: [PATCH] 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 --- docs/Makefile | 67 +++++-- docs/_ext/djangodocs.py | 23 ++- docs/_templates/genindex.html | 4 - docs/_templates/modindex.html | 3 - docs/_templates/search.html | 3 - docs/_theme/djangodocs/genindex.html | 4 + .../djangodocs}/layout.html | 4 +- docs/_theme/djangodocs/modindex.html | 3 + docs/_theme/djangodocs/search.html | 3 + .../djangodocs/static}/default.css | 0 .../djangodocs/static}/djangodocs.css | 0 .../static}/docicons-behindscenes.png | Bin .../djangodocs/static}/docicons-note.png | Bin .../static}/docicons-philosophy.png | Bin .../djangodocs/static}/homepage.css | 0 .../djangodocs/static}/reset-fonts-grids.css | 0 docs/_theme/djangodocs/theme.conf | 4 + docs/conf.py | 172 +++++++++++++++--- 18 files changed, 232 insertions(+), 58 deletions(-) delete mode 100644 docs/_templates/genindex.html delete mode 100644 docs/_templates/modindex.html delete mode 100644 docs/_templates/search.html create mode 100644 docs/_theme/djangodocs/genindex.html rename docs/{_templates => _theme/djangodocs}/layout.html (96%) create mode 100644 docs/_theme/djangodocs/modindex.html create mode 100644 docs/_theme/djangodocs/search.html rename docs/{_static => _theme/djangodocs/static}/default.css (100%) rename docs/{_static => _theme/djangodocs/static}/djangodocs.css (100%) rename docs/{_static => _theme/djangodocs/static}/docicons-behindscenes.png (100%) rename docs/{_static => _theme/djangodocs/static}/docicons-note.png (100%) rename docs/{_static => _theme/djangodocs/static}/docicons-philosophy.png (100%) rename docs/{_static => _theme/djangodocs/static}/homepage.css (100%) rename docs/{_static => _theme/djangodocs/static}/reset-fonts-grids.css (100%) create mode 100644 docs/_theme/djangodocs/theme.conf diff --git a/docs/Makefile b/docs/Makefile index f6a92b6835..9301315040 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,20 +12,26 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest help: @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: -rm -rf $(BUILDDIR)/* @@ -40,6 +46,11 @@ dirhtml: @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @@ -65,12 +76,42 @@ qthelp: @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django.qhc" +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/django" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py index efcd94d4bc..4b1edca3f6 100644 --- a/docs/_ext/djangodocs.py +++ b/docs/_ext/djangodocs.py @@ -88,7 +88,10 @@ def parse_version_directive(name, arguments, options, content, lineno, if not is_nextversion: if len(arguments) == 1: linktext = 'Please, see the release notes ' % (arguments[0]) - xrefs = sphinx.roles.xfileref_role('ref', linktext, linktext, lineno, state) + try: + xrefs = sphinx.roles.XRefRole()('ref', linktext, linktext, lineno, state) # Sphinx >= 1.0 + except: + xrefs = sphinx.roles.xfileref_role('ref', linktext, linktext, lineno, state) # Sphinx < 1.0 node.extend(xrefs[0]) node['version'] = arguments[0] else: @@ -159,7 +162,7 @@ class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator): # better callout -- the Sphinx default is just a little span, # which is a bit less obvious that I'd like. # - # FIXME: these messages are all hardcoded in English. We need to chanage + # FIXME: these messages are all hardcoded in English. We need to change # that to accomodate other language docs, but I can't work out how to make # that work and I think it'll require Sphinx 0.5 anyway. # @@ -212,7 +215,10 @@ def parse_django_admin_node(env, sig, signode): def parse_django_adminopt_node(env, sig, signode): """A copy of sphinx.directives.CmdoptionDesc.parse_signature()""" from sphinx import addnodes - from sphinx.directives.desc import option_desc_re + try: + from sphinx.domains.std import option_desc_re # Sphinx >= 1.0 + except: + from sphinx.directives.desc import option_desc_re # Sphinx < 1.0 count = 0 firstname = '' for m in option_desc_re.finditer(sig): @@ -278,9 +284,14 @@ class DjangoStandaloneHTMLBuilder(builders_html.StandaloneHTMLBuilder): self.warn("cannot create templatebuiltins.js due to missing simplejson dependency") return self.info(bold("writing templatebuiltins.js...")) - xrefs = self.env.reftargets.keys() - templatebuiltins = dict([('ttags', [n for (t,n) in xrefs if t == 'ttag']), - ('tfilters', [n for (t,n) in xrefs if t == 'tfilter'])]) + try: + xrefs = self.env.reftargets.keys() + templatebuiltins = dict([('ttags', [n for (t,n) in xrefs if t == 'ttag']), + ('tfilters', [n for (t,n) in xrefs if t == 'tfilter'])]) + except AttributeError: + xrefs = self.env.domaindata["std"]["objects"] + templatebuiltins = dict([('ttags', [n for (t,n) in xrefs if t == 'templatetag']), + ('tfilters', [n for (t,n) in xrefs if t == 'templatefilter'])]) outfilename = os.path.join(self.outdir, "templatebuiltins.js") f = open(outfilename, 'wb') f.write('var django_template_builtins = ') diff --git a/docs/_templates/genindex.html b/docs/_templates/genindex.html deleted file mode 100644 index 60c19efd45..0000000000 --- a/docs/_templates/genindex.html +++ /dev/null @@ -1,4 +0,0 @@ -{% extends "!genindex.html" %} - -{% block bodyclass %}{% endblock %} -{% block sidebarwrapper %}{% endblock %} \ No newline at end of file diff --git a/docs/_templates/modindex.html b/docs/_templates/modindex.html deleted file mode 100644 index 96a1d2080a..0000000000 --- a/docs/_templates/modindex.html +++ /dev/null @@ -1,3 +0,0 @@ -{% extends "!modindex.html" %} -{% block bodyclass %}{% endblock %} -{% block sidebarwrapper %}{% endblock %} \ No newline at end of file diff --git a/docs/_templates/search.html b/docs/_templates/search.html deleted file mode 100644 index 8bd6dbd332..0000000000 --- a/docs/_templates/search.html +++ /dev/null @@ -1,3 +0,0 @@ -{% extends "!search.html" %} -{% block bodyclass %}{% endblock %} -{% block sidebarwrapper %}{% endblock %} \ No newline at end of file diff --git a/docs/_theme/djangodocs/genindex.html b/docs/_theme/djangodocs/genindex.html new file mode 100644 index 0000000000..486994ae91 --- /dev/null +++ b/docs/_theme/djangodocs/genindex.html @@ -0,0 +1,4 @@ +{% extends "basic/genindex.html" %} + +{% block bodyclass %}{% endblock %} +{% block sidebarwrapper %}{% endblock %} \ No newline at end of file diff --git a/docs/_templates/layout.html b/docs/_theme/djangodocs/layout.html similarity index 96% rename from docs/_templates/layout.html rename to docs/_theme/djangodocs/layout.html index 70e029c3ac..ef91dd77a9 100644 --- a/docs/_templates/layout.html +++ b/docs/_theme/djangodocs/layout.html @@ -1,4 +1,4 @@ -{% extends "!layout.html" %} +{% extends "basic/layout.html" %} {%- macro secondnav() %} {%- if prev %} @@ -61,7 +61,7 @@ Home {{ reldelim2 }} Table of contents {{ reldelim2 }} Index {{ reldelim2 }} - Modules + Modules
{{ secondnav() }}
diff --git a/docs/_theme/djangodocs/modindex.html b/docs/_theme/djangodocs/modindex.html new file mode 100644 index 0000000000..59a5cb31bd --- /dev/null +++ b/docs/_theme/djangodocs/modindex.html @@ -0,0 +1,3 @@ +{% extends "basic/modindex.html" %} +{% block bodyclass %}{% endblock %} +{% block sidebarwrapper %}{% endblock %} \ No newline at end of file diff --git a/docs/_theme/djangodocs/search.html b/docs/_theme/djangodocs/search.html new file mode 100644 index 0000000000..943478ce75 --- /dev/null +++ b/docs/_theme/djangodocs/search.html @@ -0,0 +1,3 @@ +{% extends "basic/search.html" %} +{% block bodyclass %}{% endblock %} +{% block sidebarwrapper %}{% endblock %} \ No newline at end of file diff --git a/docs/_static/default.css b/docs/_theme/djangodocs/static/default.css similarity index 100% rename from docs/_static/default.css rename to docs/_theme/djangodocs/static/default.css diff --git a/docs/_static/djangodocs.css b/docs/_theme/djangodocs/static/djangodocs.css similarity index 100% rename from docs/_static/djangodocs.css rename to docs/_theme/djangodocs/static/djangodocs.css diff --git a/docs/_static/docicons-behindscenes.png b/docs/_theme/djangodocs/static/docicons-behindscenes.png similarity index 100% rename from docs/_static/docicons-behindscenes.png rename to docs/_theme/djangodocs/static/docicons-behindscenes.png diff --git a/docs/_static/docicons-note.png b/docs/_theme/djangodocs/static/docicons-note.png similarity index 100% rename from docs/_static/docicons-note.png rename to docs/_theme/djangodocs/static/docicons-note.png diff --git a/docs/_static/docicons-philosophy.png b/docs/_theme/djangodocs/static/docicons-philosophy.png similarity index 100% rename from docs/_static/docicons-philosophy.png rename to docs/_theme/djangodocs/static/docicons-philosophy.png diff --git a/docs/_static/homepage.css b/docs/_theme/djangodocs/static/homepage.css similarity index 100% rename from docs/_static/homepage.css rename to docs/_theme/djangodocs/static/homepage.css diff --git a/docs/_static/reset-fonts-grids.css b/docs/_theme/djangodocs/static/reset-fonts-grids.css similarity index 100% rename from docs/_static/reset-fonts-grids.css rename to docs/_theme/djangodocs/static/reset-fonts-grids.css diff --git a/docs/_theme/djangodocs/theme.conf b/docs/_theme/djangodocs/theme.conf new file mode 100644 index 0000000000..be43c723ae --- /dev/null +++ b/docs/_theme/djangodocs/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = basic +stylesheet = default.css +pygments_style = trac diff --git a/docs/conf.py b/docs/conf.py index 90e0a6bcb5..d3980a530f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,17 +8,21 @@ # The contents of this file are pickled, so don't put values in the namespace # that aren't pickleable (module imports are okay, they're removed automatically). # -# All configuration values have a default value; values that are commented out -# serve to show the default value. +# All configuration values have a default; values that are commented out +# serve to show the default. import sys import os -# If your extensions are in another directory, add it here. -sys.path.append(os.path.join(os.path.dirname(__file__), "_ext")) +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext"))) -# General configuration -# --------------------- +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. @@ -30,6 +34,9 @@ templates_path = ["_templates"] # The suffix of source filenames. source_suffix = '.txt' +# The encoding of source files. +#source_encoding = 'utf-8-sig' + # The master toctree document. master_doc = 'contents' @@ -37,8 +44,10 @@ master_doc = 'contents' project = 'Django' copyright = 'Django Software Foundation and contributors' -# The default replacements for |version| and |release|, also used in various -# other places throughout the built documents. + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. # # The short X.Y version. version = '1.2' @@ -47,14 +56,22 @@ release = version # The next version to be released django_next_version = '1.3' +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. today_fmt = '%B %d, %Y' -# List of documents that shouldn't be included in the build. -#unused_docs = [] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True @@ -75,13 +92,35 @@ pygments_style = 'trac' # Note: exclude_dirnames is new in Sphinx 0.5 exclude_dirnames = ['.svn'] -# Options for HTML output -# ----------------------- +# -- Options for HTML output --------------------------------------------------- -# The style sheet to use for HTML and HTML Help pages. A file of that name -# must exist either in Sphinx' static/ path, or in one of the custom paths -# given in html_static_path. -html_style = 'default.css' +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = "djangodocs" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ["_theme"] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -110,17 +149,38 @@ html_translator_class = "djangodocs.DjangoHTMLTranslator" html_additional_pages = {} # If false, no module index is generated. -#html_use_modindex = True +#html_domain_indices = True -# If true, the reST sources are included in the HTML build as _sources/. -html_copy_source = True +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'Djangodoc' +modindex_common_prefix = ["django."] -# Options for LaTeX output -# ------------------------ + +# -- Options for LaTeX output -------------------------------------------------- # The paper size ('letter' or 'a4'). #latex_paper_size = 'letter' @@ -132,9 +192,24 @@ htmlhelp_basename = 'Djangodoc' # (source start file, target name, title, author, document class [howto/manual]). #latex_documents = [] latex_documents = [ - ('contents', 'django.tex', 'Django Documentation', 'Django Software Foundation', 'manual'), + ('contents', 'django.tex', u'Django Documentation', + u'Django Software Foundation', 'manual'), ] +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + # Additional stuff for the LaTeX preamble. #latex_preamble = '' @@ -142,10 +217,53 @@ latex_documents = [ #latex_appendices = [] # If false, no module index is generated. -#latex_use_modindex = True +#latex_domain_indices = True -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# If this isn't set to True, the LaTex writer can only handle six levels of headers. -latex_use_parts = True +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('contents', 'django', 'Django Documentation', ['Django Software Foundation'], 1) +] + + +# -- Options for Epub output --------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'Django' +epub_author = u'Django Software Foundation' +epub_publisher = u'Django Software Foundation' +epub_copyright = u'2010, Django Software Foundation' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +#epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True