diff options
Diffstat (limited to 'docs')
47 files changed, 695 insertions, 397 deletions
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 <target>' where <target> 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..cee14ba6f1 100644 --- a/docs/_ext/djangodocs.py +++ b/docs/_ext/djangodocs.py @@ -1,9 +1,9 @@ """ Sphinx plugins for Django documentation. """ +import os -import docutils.nodes -import docutils.transforms +from docutils import nodes, transforms try: import json except ImportError: @@ -14,26 +14,12 @@ except ImportError: from django.utils import simplejson as json except ImportError: json = None -import os -import sphinx -import sphinx.addnodes -try: - from sphinx import builders -except ImportError: - import sphinx.builder as builders -try: - import sphinx.builders.html as builders_html -except ImportError: - builders_html = builders + +from sphinx import addnodes, roles +from sphinx.builders.html import StandaloneHTMLBuilder +from sphinx.writers.html import SmartyPantsHTMLTranslator from sphinx.util.console import bold -import sphinx.directives -import sphinx.environment -try: - import sphinx.writers.html as sphinx_htmlwriter -except ImportError: - import sphinx.htmlwriter as sphinx_htmlwriter -import sphinx.roles -from docutils import nodes + def setup(app): app.add_crossref_type( @@ -74,21 +60,20 @@ def setup(app): app.add_transform(SuppressBlockquotes) app.add_builder(DjangoStandaloneHTMLBuilder) - # Monkeypatch PickleHTMLBuilder so that it doesn't die in Sphinx 0.4.2 - if sphinx.__version__ == '0.4.2': - monkeypatch_pickle_builder() - def parse_version_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): env = state.document.settings.env is_nextversion = env.config.django_next_version == arguments[0] ret = [] - node = sphinx.addnodes.versionmodified() + node = addnodes.versionmodified() ret.append(node) if not is_nextversion: if len(arguments) == 1: linktext = 'Please, see the release notes <releases-%s>' % (arguments[0]) - xrefs = sphinx.roles.xfileref_role('ref', linktext, linktext, lineno, state) + try: + xrefs = roles.XRefRole()('ref', linktext, linktext, lineno, state) # Sphinx >= 1.0 + except: + xrefs = roles.xfileref_role('ref', linktext, linktext, lineno, state) # Sphinx < 1.0 node.extend(xrefs[0]) node['version'] = arguments[0] else: @@ -103,29 +88,29 @@ def parse_version_directive(name, arguments, options, content, lineno, env.note_versionchange(node['type'], node['version'], node, lineno) return ret - -class SuppressBlockquotes(docutils.transforms.Transform): + +class SuppressBlockquotes(transforms.Transform): """ Remove the default blockquotes that encase indented list, tables, etc. """ default_priority = 300 - + suppress_blockquote_child_nodes = ( - docutils.nodes.bullet_list, - docutils.nodes.enumerated_list, - docutils.nodes.definition_list, - docutils.nodes.literal_block, - docutils.nodes.doctest_block, - docutils.nodes.line_block, - docutils.nodes.table + nodes.bullet_list, + nodes.enumerated_list, + nodes.definition_list, + nodes.literal_block, + nodes.doctest_block, + nodes.line_block, + nodes.table ) - + def apply(self): - for node in self.document.traverse(docutils.nodes.block_quote): + for node in self.document.traverse(nodes.block_quote): if len(node.children) == 1 and isinstance(node.children[0], self.suppress_blockquote_child_nodes): node.replace_self(node.children[0]) -class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator): +class DjangoHTMLTranslator(SmartyPantsHTMLTranslator): """ Django-specific reST to HTML tweaks. """ @@ -133,42 +118,41 @@ class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator): # Don't use border=1, which docutils does by default. def visit_table(self, node): self.body.append(self.starttag(node, 'table', CLASS='docutils')) - + # <big>? Really? def visit_desc_parameterlist(self, node): self.body.append('(') self.first_param = 1 - + def depart_desc_parameterlist(self, node): self.body.append(')') - pass - + # # Don't apply smartypants to literal blocks # def visit_literal_block(self, node): self.no_smarty += 1 - sphinx_htmlwriter.SmartyPantsHTMLTranslator.visit_literal_block(self, node) + SmartyPantsHTMLTranslator.visit_literal_block(self, node) def depart_literal_block(self, node): - sphinx_htmlwriter.SmartyPantsHTMLTranslator.depart_literal_block(self, node) + SmartyPantsHTMLTranslator.depart_literal_block(self, node) self.no_smarty -= 1 - + # - # Turn the "new in version" stuff (versoinadded/versionchanged) into a + # Turn the "new in version" stuff (versionadded/versionchanged) into a # 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. + # that work. # version_text = { 'deprecated': 'Deprecated in Django %s', 'versionchanged': 'Changed in Django %s', 'versionadded': 'New in Django %s', } - + def visit_versionmodified(self, node): self.body.append( self.starttag(node, 'div', CLASS=node['type']) @@ -178,41 +162,31 @@ class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator): len(node) and ":" or "." ) self.body.append('<span class="title">%s</span> ' % title) - + def depart_versionmodified(self, node): self.body.append("</div>\n") - - # Give each section a unique ID -- nice for custom CSS hooks - # This is different on docutils 0.5 vs. 0.4... - if hasattr(sphinx_htmlwriter.SmartyPantsHTMLTranslator, 'start_tag_with_title') and sphinx.__version__ == '0.4.2': - def start_tag_with_title(self, node, tagname, **atts): - node = { - 'classes': node.get('classes', []), - 'ids': ['s-%s' % i for i in node.get('ids', [])] - } - return self.starttag(node, tagname, **atts) - - else: - def visit_section(self, node): - old_ids = node.get('ids', []) - node['ids'] = ['s-' + i for i in old_ids] - if sphinx.__version__ != '0.4.2': - node['ids'].extend(old_ids) - sphinx_htmlwriter.SmartyPantsHTMLTranslator.visit_section(self, node) - node['ids'] = old_ids + # Give each section a unique ID -- nice for custom CSS hooks + def visit_section(self, node): + old_ids = node.get('ids', []) + node['ids'] = ['s-' + i for i in old_ids] + node['ids'].extend(old_ids) + SmartyPantsHTMLTranslator.visit_section(self, node) + node['ids'] = old_ids def parse_django_admin_node(env, sig, signode): command = sig.split(' ')[0] env._django_curr_admin_command = command title = "django-admin.py %s" % sig - signode += sphinx.addnodes.desc_name(title, title) + signode += addnodes.desc_name(title, title) return sig 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): @@ -228,44 +202,8 @@ def parse_django_adminopt_node(env, sig, signode): raise ValueError return firstname -def monkeypatch_pickle_builder(): - import shutil - from os import path - try: - import cPickle as pickle - except ImportError: - import pickle - - def handle_finish(self): - # dump the global context - outfilename = path.join(self.outdir, 'globalcontext.pickle') - f = open(outfilename, 'wb') - try: - pickle.dump(self.globalcontext, f, 2) - finally: - f.close() - - self.info(bold('dumping search index...')) - self.indexer.prune(self.env.all_docs) - f = open(path.join(self.outdir, 'searchindex.pickle'), 'wb') - try: - self.indexer.dump(f, 'pickle') - finally: - f.close() - - # copy the environment file from the doctree dir to the output dir - # as needed by the web app - shutil.copyfile(path.join(self.doctreedir, builders.ENV_PICKLE_FILENAME), - path.join(self.outdir, builders.ENV_PICKLE_FILENAME)) - # touch 'last build' file, used by the web application to determine - # when to reload its environment and clear the cache - open(path.join(self.outdir, builders.LAST_BUILD_FILENAME), 'w').close() - - builders.PickleHTMLBuilder.handle_finish = handle_finish - - -class DjangoStandaloneHTMLBuilder(builders_html.StandaloneHTMLBuilder): +class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder): """ Subclass to add some extra things we need. """ @@ -278,9 +216,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 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 @@ <a title="Home page" href="{{ pathto('index') }}">Home</a> {{ reldelim2 }} <a title="Table of contents" href="{{ pathto('contents') }}">Table of contents</a> {{ reldelim2 }} <a title="Global index" href="{{ pathto('genindex') }}">Index</a> {{ reldelim2 }} - <a title="Module index" href="{{ pathto('modindex') }}">Modules</a> + <a title="Module index" href="{{ pathto('py-modindex') }}">Modules</a> </div> <div class="nav">{{ secondnav() }}</div> </div> 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 index 9dc69ee785..9dc69ee785 100644 --- a/docs/_static/default.css +++ b/docs/_theme/djangodocs/static/default.css diff --git a/docs/_static/djangodocs.css b/docs/_theme/djangodocs/static/djangodocs.css index 4adb8387cc..4adb8387cc 100644 --- a/docs/_static/djangodocs.css +++ b/docs/_theme/djangodocs/static/djangodocs.css diff --git a/docs/_static/docicons-behindscenes.png b/docs/_theme/djangodocs/static/docicons-behindscenes.png Binary files differindex dc901bc867..dc901bc867 100644 --- a/docs/_static/docicons-behindscenes.png +++ b/docs/_theme/djangodocs/static/docicons-behindscenes.png diff --git a/docs/_static/docicons-note.png b/docs/_theme/djangodocs/static/docicons-note.png Binary files differindex 357545fb32..357545fb32 100644 --- a/docs/_static/docicons-note.png +++ b/docs/_theme/djangodocs/static/docicons-note.png diff --git a/docs/_static/docicons-philosophy.png b/docs/_theme/djangodocs/static/docicons-philosophy.png Binary files differindex 09f16c785b..09f16c785b 100644 --- a/docs/_static/docicons-philosophy.png +++ b/docs/_theme/djangodocs/static/docicons-philosophy.png diff --git a/docs/_static/homepage.css b/docs/_theme/djangodocs/static/homepage.css index 276c5470ab..276c5470ab 100644 --- a/docs/_static/homepage.css +++ b/docs/_theme/djangodocs/static/homepage.css diff --git a/docs/_static/reset-fonts-grids.css b/docs/_theme/djangodocs/static/reset-fonts-grids.css index f5238d7c91..f5238d7c91 100644 --- a/docs/_static/reset-fonts-grids.css +++ b/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..606ee6b5ad 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,28 +8,35 @@ # 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. extensions = ["djangodocs"] # Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] +# templates_path = [] # 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 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 +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None -# 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 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 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, the reST sources are included in the HTML build as _sources/<name>. -html_copy_source = 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 <link> 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 diff --git a/docs/faq/install.txt b/docs/faq/install.txt index 0139a82a67..f5feb98aff 100644 --- a/docs/faq/install.txt +++ b/docs/faq/install.txt @@ -19,7 +19,7 @@ What are Django's prerequisites? -------------------------------- Django requires Python_, specifically any version of Python from 2.4 -through 2.6. No other Python libraries are required for basic Django +through 2.7. No other Python libraries are required for basic Django usage. For a development environment -- if you just want to experiment with Django -- diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt index c555f205b1..41d1cffdb2 100644 --- a/docs/internals/contributing.txt +++ b/docs/internals/contributing.txt @@ -145,7 +145,11 @@ and time availability), claim it by following these steps: * Claim the ticket by clicking the radio button next to "Accept ticket" near the bottom of the page, then clicking "Submit changes." +If you have an account but have forgotten your password, you can reset it +using the `password reset page`_. + .. _Create an account: http://www.djangoproject.com/accounts/register/ +.. _password reset page: http://www.djangoproject.com/accounts/password/reset/ Ticket claimers' responsibility ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/internals/documentation.txt b/docs/internals/documentation.txt index 81480abf9a..9aa8551266 100644 --- a/docs/internals/documentation.txt +++ b/docs/internals/documentation.txt @@ -15,6 +15,11 @@ __ http://docutils.sourceforge.net/ To actually build the documentation locally, you'll currently need to install Sphinx -- ``easy_install Sphinx`` should do the trick. +.. note:: + + Generation of the Django documentation will work with Sphinx version 0.6 + or newer, but we recommend going straigh to Sphinx 1.0 or newer. + Then, building the html is easy; just ``make html`` from the ``docs`` directory. To get started contributing, you'll want to read the `ReStructuredText diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index f7aefa457d..1fbae3f060 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -474,17 +474,16 @@ change list page. By default, this is set to ``100``. .. attribute:: ModelAdmin.list_select_related -Set ``list_select_related`` to tell Django to use ``select_related()`` in -retrieving the list of objects on the admin change list page. This can save you -a bunch of database queries. +Set ``list_select_related`` to tell Django to use +:meth:`~django.db.models.QuerySet.select_related` in retrieving the list of +objects on the admin change list page. This can save you a bunch of database +queries. The value should be either ``True`` or ``False``. Default is ``False``. -Note that Django will use ``select_related()``, regardless of this setting, -if one of the ``list_display`` fields is a ``ForeignKey``. - -For more on ``select_related()``, see -:ref:`the select_related() docs <select-related>`. +Note that Django will use :meth:`~django.db.models.QuerySet.select_related`, +regardless of this setting, if one of the ``list_display`` fields is a +``ForeignKey``. .. attribute:: ModelAdmin.inlines @@ -595,11 +594,16 @@ This should be set to a list of field names that will be searched whenever somebody submits a search query in that text box. These fields should be some kind of text field, such as ``CharField`` or -``TextField``. You can also perform a related lookup on a ``ForeignKey`` with -the lookup API "follow" notation:: +``TextField``. You can also perform a related lookup on a ``ForeignKey`` or +``ManyToManyField`` with the lookup API "follow" notation:: search_fields = ['foreign_key__related_fieldname'] +For example, if you have a blog entry with an author, the following definition +would enable search blog entries by the email address of the author:: + + search_fields = ['user__email'] + When somebody does a search in the admin search box, Django splits the search query into words and returns all objects that contain each of the words, case insensitive, where each word must be in at least one of ``search_fields``. For @@ -865,11 +869,26 @@ return a subset of objects for this foreign key field based on the user:: def formfield_for_foreignkey(self, db_field, request, **kwargs): if db_field.name == "car": kwargs["queryset"] = Car.objects.filter(owner=request.user) - return db_field.formfield(**kwargs) return super(MyModelAdmin, self).formfield_for_foreignkey(db_field, request, **kwargs) This uses the ``HttpRequest`` instance to filter the ``Car`` foreign key field -to only the cars owned by the ``User`` instance. +to only display the cars owned by the ``User`` instance. + +.. method:: ModelAdmin.formfield_for_manytomany(self, db_field, request, **kwargs) + +.. versionadded:: 1.1 + +Like the ``formfield_for_foreignkey`` method, the ``formfield_for_manytomany`` +method can be overridden to change the default formfield for a many to many +field. For example, if an owner can own multiple cars and cars can belong +to multiple owners -- a many to many relationship -- you could filter the +``Car`` foreign key field to only display the cars owned by the ``User``:: + + class MyModelAdmin(admin.ModelAdmin): + def formfield_for_manytomany(self, db_field, request, **kwargs): + if db_field.name == "cars": + kwargs["queryset"] = Car.objects.filter(owner=request.user) + return super(MyModelAdmin, self).formfield_for_manytomany(db_field, request, **kwargs) .. method:: ModelAdmin.queryset(self, request) @@ -1027,90 +1046,88 @@ The difference between these two is merely the template used to render them. The ``InlineModelAdmin`` class is a subclass of ``ModelAdmin`` so it inherits all the same functionality as well as some of its own: -``model`` -~~~~~~~~~ +.. attribute:: InlineModelAdmin.model -The model in which the inline is using. This is required. + The model in which the inline is using. This is required. -``fk_name`` -~~~~~~~~~~~ +.. attribute:: InlineModelAdmin.fk_name -The name of the foreign key on the model. In most cases this will be dealt -with automatically, but ``fk_name`` must be specified explicitly if there are -more than one foreign key to the same parent model. + The name of the foreign key on the model. In most cases this will be dealt + with automatically, but ``fk_name`` must be specified explicitly if there + are more than one foreign key to the same parent model. -``formset`` -~~~~~~~~~~~ +.. attribute:: InlineModelAdmin.formset -This defaults to ``BaseInlineFormSet``. Using your own formset can give you -many possibilities of customization. Inlines are built around -:ref:`model formsets <model-formsets>`. + This defaults to ``BaseInlineFormSet``. Using your own formset can give you + many possibilities of customization. Inlines are built around + :ref:`model formsets <model-formsets>`. -``form`` -~~~~~~~~ +.. attribute:: InlineModelAdmin.form -The value for ``form`` defaults to ``ModelForm``. This is what is -passed through to ``inlineformset_factory`` when creating the formset for this -inline. + The value for ``form`` defaults to ``ModelForm``. This is what is passed + through to ``inlineformset_factory`` when creating the formset for this + inline. .. _ref-contrib-admin-inline-extra: -``extra`` -~~~~~~~~~ +.. attribute:: InlineModelAdmin.extra -This controls the number of extra forms the formset will display in addition -to the initial forms. See the -:ref:`formsets documentation <topics-forms-formsets>` for more information. -.. versionadded:: 1.2 + This controls the number of extra forms the formset will display in addition + to the initial forms. See the + :ref:`formsets documentation <topics-forms-formsets>` for more information. + + .. versionadded:: 1.2 -For users with JavaScript-enabled browsers, an "Add another" link is -provided to enable any number of additional inlines to be added in -addition to those provided as a result of the ``extra`` argument. + For users with JavaScript-enabled browsers, an "Add another" link is + provided to enable any number of additional inlines to be added in addition + to those provided as a result of the ``extra`` argument. -The dynamic link will not appear if the number of currently displayed -forms exceeds ``max_num``, or if the user does not have JavaScript -enabled. + The dynamic link will not appear if the number of currently displayed forms + exceeds ``max_num``, or if the user does not have JavaScript enabled. .. _ref-contrib-admin-inline-max-num: -``max_num`` -~~~~~~~~~~~ +.. attribute:: InlineModelAdmin.max_num -This controls the maximum number of forms to show in the inline. This doesn't -directly correlate to the number of objects, but can if the value is small -enough. See :ref:`model-formsets-max-num` for more information. + This controls the maximum number of forms to show in the inline. This + doesn't directly correlate to the number of objects, but can if the value + is small enough. See :ref:`model-formsets-max-num` for more information. -``raw_id_fields`` -~~~~~~~~~~~~~~~~~ +.. attribute:: InlineModelAdmin.raw_id_fields -By default, Django's admin uses a select-box interface (<select>) for -fields that are ``ForeignKey``. Sometimes you don't want to incur the -overhead of having to select all the related instances to display in the -drop-down. + By default, Django's admin uses a select-box interface (<select>) for + fields that are ``ForeignKey``. Sometimes you don't want to incur the + overhead of having to select all the related instances to display in the + drop-down. -``raw_id_fields`` is a list of fields you would like to change -into a ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``:: + ``raw_id_fields`` is a list of fields you would like to change into a + ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``:: - class BookInline(admin.TabularInline): - model = Book - raw_id_fields = ("pages",) + class BookInline(admin.TabularInline): + model = Book + raw_id_fields = ("pages",) -``template`` -~~~~~~~~~~~~ -The template used to render the inline on the page. +.. attribute:: InlineModelAdmin.template -``verbose_name`` -~~~~~~~~~~~~~~~~ + The template used to render the inline on the page. -An override to the ``verbose_name`` found in the model's inner ``Meta`` class. +.. attribute:: InlineModelAdmin.verbose_name -``verbose_name_plural`` -~~~~~~~~~~~~~~~~~~~~~~~ + An override to the ``verbose_name`` found in the model's inner ``Meta`` + class. + +.. attribute:: InlineModelAdmin.verbose_name_plural + + An override to the ``verbose_name_plural`` found in the model's inner + ``Meta`` class. + +.. attribute:: InlineModelAdmin.can_delete + + Specifies whether or not inline objects can be deleted in the inline. + Defaults to ``True``. -An override to the ``verbose_name_plural`` found in the model's inner ``Meta`` -class. Working with a model with two or more foreign keys to the same parent model --------------------------------------------------------------------------- diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 3085bf3ee9..da5d934d38 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -324,15 +324,19 @@ same types of lookups manually:: ... object_id=b.id) [<TaggedItem: django>, <TaggedItem: python>] -Note that if the model with a :class:`~django.contrib.contenttypes.generic.GenericForeignKey` -that you're referring to uses a non-default value for ``ct_field`` or ``fk_field`` -(e.g. the :mod:`django.contrib.comments` app uses ``ct_field="object_pk"``), -you'll need to pass ``content_type_field`` and ``object_id_field`` to -:class:`~django.contrib.contenttypes.generic.GenericRelation`.:: - - comments = generic.GenericRelation(Comment, content_type_field="content_type", object_id_field="object_pk") - -Note that if you delete an object that has a +Note that if the model in a +:class:`~django.contrib.contenttypes.generic.GenericRelation` uses a +non-default value for ``ct_field`` or ``fk_field`` in its +:class:`~django.contrib.contenttypes.generic.GenericForeignKey` (e.g. the +:mod:`django.contrib.comments` app uses ``ct_field="object_pk"``), +you'll need to set ``content_type_field`` and/or ``object_id_field`` in +the :class:`~django.contrib.contenttypes.generic.GenericRelation` to +match the ``ct_field`` and ``fk_field``, respectively, in the +:class:`~django.contrib.contenttypes.generic.GenericForeignKey`:: + + comments = generic.GenericRelation(Comment, object_id_field="object_pk") + +Note also, that if you delete an object that has a :class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects which have a :class:`~django.contrib.contenttypes.generic.GenericForeignKey` pointing at it will be deleted as well. In the example above, this means that diff --git a/docs/ref/contrib/formtools/form-wizard.txt b/docs/ref/contrib/formtools/form-wizard.txt index 5ef862ce3d..8dcebd1d6f 100644 --- a/docs/ref/contrib/formtools/form-wizard.txt +++ b/docs/ref/contrib/formtools/form-wizard.txt @@ -189,8 +189,10 @@ for the wizard to work properly. Hooking the wizard into a URLconf ================================= -Finally, give your new :class:`FormWizard` object a URL in ``urls.py``. The -wizard takes a list of your :class:`~django.forms.Form` objects as arguments:: +Finally, we need to specify which forms to use in the wizard, and then +deploy the new :class:`FormWizard` object a URL in ``urls.py``. The +wizard takes a list of your :class:`~django.forms.Form` objects as +arguments when you instantiate the Wizard:: from django.conf.urls.defaults import * from mysite.testapp.forms import ContactForm1, ContactForm2, ContactWizard diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 542a71582d..83aa97240c 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -227,6 +227,11 @@ pretty-print the output with a number of indentation spaces. The :djadminopt:`--exclude` option may be provided to prevent specific applications from being dumped. +.. versionadded:: 1.3 + +The :djadminopt:`--exclude` option may also be provided to prevent specific +models (specified as in the form of ``appname.ModelName``) from being dumped. + .. versionadded:: 1.1 In addition to specifying application names, you can provide a list of @@ -957,6 +962,7 @@ that ``django-admin.py`` should print to the console. * ``0`` means no output. * ``1`` means normal output (default). * ``2`` means verbose output. + * ``3`` means *very* verbose output. Common options ============== diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 1fc2bfa85d..e82fae7761 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -6,7 +6,7 @@ Widgets .. module:: django.forms.widgets :synopsis: Django's built-in form widgets. - + .. currentmodule:: django.forms A widget is Django's representation of a HTML input element. The widget @@ -29,7 +29,12 @@ commonly used groups of widgets: .. attribute:: PasswordInput.render_value Determines whether the widget will have a value filled in when the - form is re-displayed after a validation error (default is ``True``). + form is re-displayed after a validation error (default is ``False``). + +.. versionchanged:: 1.3 + The default value for + :attr:`~PasswordInput.render_value` was + changed from ``True`` to ``False`` .. class:: HiddenInput @@ -50,7 +55,7 @@ commonly used groups of widgets: Date input as a simple text box: ``<input type='text' ...>`` Takes one optional argument: - + .. attribute:: DateInput.format The format in which this field's initial value will be displayed. @@ -64,11 +69,11 @@ commonly used groups of widgets: Date/time input as a simple text box: ``<input type='text' ...>`` Takes one optional argument: - + .. attribute:: DateTimeInput.format - + The format in which this field's initial value will be displayed. - + If no ``format`` argument is provided, the default format is ``'%Y-%m-%d %H:%M:%S'``. @@ -77,11 +82,11 @@ commonly used groups of widgets: Time input as a simple text box: ``<input type='text' ...>`` Takes one optional argument: - + .. attribute:: TimeInput.format - + The format in which this field's initial value will be displayed. - + If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``. .. versionchanged:: 1.1 @@ -98,15 +103,15 @@ commonly used groups of widgets: Takes one optional argument: .. attribute:: CheckboxInput.check_test - - A callable that takes the value of the CheckBoxInput + + A callable that takes the value of the CheckBoxInput and returns ``True`` if the checkbox should be checked for - that value. + that value. .. class:: Select Select widget: ``<select><option ...>...</select>`` - + Requires that your field provides :attr:`~Field.choices`. .. class:: NullBooleanSelect @@ -123,22 +128,22 @@ commonly used groups of widgets: .. class:: RadioSelect A list of radio buttons: - + .. code-block:: html - + <ul> <li><input type='radio' ...></li> ... </ul> - + Requires that your field provides :attr:`~Field.choices`. .. class:: CheckboxSelectMultiple A list of checkboxes: - + .. code-block:: html - + <ul> <li><input type='checkbox' ...></li> ... @@ -155,7 +160,7 @@ commonly used groups of widgets: Takes two optional arguments, ``date_format`` and ``time_format``, which work just like the ``format`` argument for ``DateInput`` and ``TimeInput``. - + .. versionchanged:: 1.1 The ``date_format`` and ``time_format`` arguments were not supported in Django 1.0. diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index dd14dd1ce7..1e72e0c662 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -107,7 +107,7 @@ special key that is used for errors that are tied to the entire model instead of to a specific field. You can access these errors with ``NON_FIELD_ERRORS``:: - from django.core.validators import ValidationError, NON_FIELD_ERRORS + from django.core.exceptions import ValidationError, NON_FIELD_ERRORS try: article.full_clean() except ValidationError, e: diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 56ff6444e4..91d1415043 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -332,8 +332,6 @@ a model which defines a default ordering, or when using ordering was undefined prior to calling ``reverse()``, and will remain undefined afterward). -.. _queryset-distinct: - ``distinct()`` ~~~~~~~~~~~~~~ @@ -367,9 +365,6 @@ query spans multiple tables, it's possible to get duplicate results when a ``values()`` together, be careful when ordering by fields not in the ``values()`` call. - -.. _queryset-values: - ``values(*fields)`` ~~~~~~~~~~~~~~~~~~~ @@ -679,8 +674,6 @@ related object. ``OneToOneFields`` will not be traversed in the reverse direction if you are performing a depth-based ``select_related``. -.. _queryset-extra: - ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -843,8 +836,6 @@ of the arguments is required, but you should use at least one of them. Entry.objects.extra(where=['headline=%s'], params=['Lennon']) -.. _queryset-defer: - ``defer(*fields)`` ~~~~~~~~~~~~~~~~~~ @@ -1143,8 +1134,6 @@ Example:: If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary. -.. _queryset-iterator: - ``iterator()`` ~~~~~~~~~~~~~~ diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index 2c874a1a83..d111e4c127 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -498,11 +498,11 @@ Methods .. method:: HttpResponse.__delitem__(header) Deletes the header with the given name. Fails silently if the header - doesn't exist. Case-sensitive. + doesn't exist. Case-insensitive. .. method:: HttpResponse.__getitem__(header) - Returns the value for the given header name. Case-sensitive. + Returns the value for the given header name. Case-insensitive. .. method:: HttpResponse.has_header(header) diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 53fbfb2ffe..f3c5656a9a 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -152,18 +152,6 @@ Default: ``600`` The default number of seconds to cache a page when the caching middleware or ``cache_page()`` decorator is used. -.. setting:: CSRF_COOKIE_NAME - -CSRF_COOKIE_NAME ----------------- - -.. versionadded:: 1.2 - -Default: ``'csrftoken'`` - -The name of the cookie to use for the CSRF authentication token. This can be whatever you -want. See :ref:`ref-contrib-csrf`. - .. setting:: CSRF_COOKIE_DOMAIN CSRF_COOKIE_DOMAIN @@ -179,6 +167,18 @@ request forgery protection. It should be set to a string such as ``".lawrence.com"`` to allow a POST request from a form on one subdomain to be accepted by accepted by a view served from another subdomain. +.. setting:: CSRF_COOKIE_NAME + +CSRF_COOKIE_NAME +---------------- + +.. versionadded:: 1.2 + +Default: ``'csrftoken'`` + +The name of the cookie to use for the CSRF authentication token. This can be whatever you +want. See :ref:`ref-contrib-csrf`. + .. setting:: CSRF_FAILURE_VIEW CSRF_FAILURE_VIEW @@ -573,29 +573,29 @@ Default: ``'webmaster@localhost'`` Default e-mail address to use for various automated correspondence from the site manager(s). -.. setting:: DEFAULT_TABLESPACE +.. setting:: DEFAULT_INDEX_TABLESPACE -DEFAULT_TABLESPACE ------------------- +DEFAULT_INDEX_TABLESPACE +------------------------ .. versionadded:: 1.0 Default: ``''`` (Empty string) -Default tablespace to use for models that don't specify one, if the -backend supports it. +Default tablespace to use for indexes on fields that don't specify +one, if the backend supports it. -.. setting:: DEFAULT_INDEX_TABLESPACE +.. setting:: DEFAULT_TABLESPACE -DEFAULT_INDEX_TABLESPACE ------------------------- +DEFAULT_TABLESPACE +------------------ .. versionadded:: 1.0 Default: ``''`` (Empty string) -Default tablespace to use for indexes on fields that don't specify -one, if the backend supports it. +Default tablespace to use for models that don't specify one, if the +backend supports it. .. setting:: DISALLOWED_USER_AGENTS @@ -738,21 +738,6 @@ Default: ``2621440`` (i.e. 2.5 MB). The maximum size (in bytes) that an upload will be before it gets streamed to the file system. See :ref:`topics-files` for details. -.. setting:: FILE_UPLOAD_TEMP_DIR - -FILE_UPLOAD_TEMP_DIR --------------------- - -.. versionadded:: 1.0 - -Default: ``None`` - -The directory to store data temporarily while uploading files. If ``None``, -Django will use the standard temporary directory for the operating system. For -example, this will default to '/tmp' on \*nix-style operating systems. - -See :ref:`topics-files` for details. - .. setting:: FILE_UPLOAD_PERMISSIONS FILE_UPLOAD_PERMISSIONS @@ -781,6 +766,21 @@ system's standard umask. .. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod +.. setting:: FILE_UPLOAD_TEMP_DIR + +FILE_UPLOAD_TEMP_DIR +-------------------- + +.. versionadded:: 1.0 + +Default: ``None`` + +The directory to store data temporarily while uploading files. If ``None``, +Django will use the standard temporary directory for the operating system. For +example, this will default to '/tmp' on \*nix-style operating systems. + +See :ref:`topics-files` for details. + .. setting:: FIRST_DAY_OF_WEEK FIRST_DAY_OF_WEEK @@ -1227,27 +1227,6 @@ Default: ``'root@localhost'`` The e-mail address that error messages come from, such as those sent to ``ADMINS`` and ``MANAGERS``. -.. setting:: SESSION_ENGINE - -SESSION_ENGINE --------------- - -.. versionadded:: 1.0 - -.. versionchanged:: 1.1 - The ``cached_db`` backend was added - -Default: ``django.contrib.sessions.backends.db`` - -Controls where Django stores session data. Valid values are: - - * ``'django.contrib.sessions.backends.db'`` - * ``'django.contrib.sessions.backends.file'`` - * ``'django.contrib.sessions.backends.cache'`` - * ``'django.contrib.sessions.backends.cached_db'`` - -See :ref:`topics-http-sessions`. - .. setting:: SESSION_COOKIE_AGE SESSION_COOKIE_AGE @@ -1306,6 +1285,27 @@ Whether to use a secure cookie for the session cookie. If this is set to ensure that the cookie is only sent under an HTTPS connection. See the :ref:`topics-http-sessions`. +.. setting:: SESSION_ENGINE + +SESSION_ENGINE +-------------- + +.. versionadded:: 1.0 + +.. versionchanged:: 1.1 + The ``cached_db`` backend was added + +Default: ``django.contrib.sessions.backends.db`` + +Controls where Django stores session data. Valid values are: + + * ``'django.contrib.sessions.backends.db'`` + * ``'django.contrib.sessions.backends.file'`` + * ``'django.contrib.sessions.backends.cache'`` + * ``'django.contrib.sessions.backends.cached_db'`` + +See :ref:`topics-http-sessions`. + .. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE SESSION_EXPIRE_AT_BROWSER_CLOSE @@ -1601,6 +1601,20 @@ A boolean that specifies whether to output the "Etag" header. This saves bandwidth but slows down performance. This is only used if ``CommonMiddleware`` is installed (see :ref:`topics-http-middleware`). +.. setting:: USE_I18N + +USE_I18N +-------- + +Default: ``True`` + +A boolean that specifies whether Django's internationalization system should be +enabled. This provides an easy way to turn it off, for performance. If this is +set to ``False``, Django will make some optimizations so as not to load the +internationalization machinery. + +See also ``USE_L10N`` + .. setting:: USE_L10N USE_L10N @@ -1616,20 +1630,6 @@ format of the current locale. See also ``USE_I18N`` and ``LANGUAGE_CODE`` -.. setting:: USE_I18N - -USE_I18N --------- - -Default: ``True`` - -A boolean that specifies whether Django's internationalization system should be -enabled. This provides an easy way to turn it off, for performance. If this is -set to ``False``, Django will make some optimizations so as not to load the -internationalization machinery. - -See also ``USE_L10N`` - .. setting:: USE_THOUSAND_SEPARATOR USE_THOUSAND_SEPARATOR diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index 12372dd0f1..a4dc0f705d 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -33,9 +33,9 @@ module system. If you override these methods on your model, you must call the parent class' methods for this signals to be sent. - Note also that Django stores signal handlers as weak references by default, - so if your handler is a local function, it may be garbage collected. To - prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`. + Note also that Django stores signal handlers as weak references by default, + so if your handler is a local function, it may be garbage collected. To + prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`. pre_init -------- @@ -113,6 +113,9 @@ Arguments sent with this signal: ``instance`` The actual instance being saved. + ``using`` + The database alias being used. + post_save --------- @@ -133,6 +136,9 @@ Arguments sent with this signal: ``created`` A boolean; ``True`` if a new record was created. + ``using`` + The database alias being used. + pre_delete ---------- @@ -150,6 +156,9 @@ Arguments sent with this signal: ``instance`` The actual instance being deleted. + ``using`` + The database alias being used. + post_delete ----------- @@ -170,6 +179,9 @@ Arguments sent with this signal: Note that the object will no longer be in the database, so be very careful what you do with this instance. + ``using`` + The database alias being used. + m2m_changed ----------- @@ -215,8 +227,8 @@ Arguments sent with this signal: Sent *after* the relation is cleared ``reverse`` - Indicates which side of the relation is updated (i.e., if it is the - forward or reverse relation that is being modified). + Indicates which side of the relation is updated (i.e., if it is the + forward or reverse relation that is being modified). ``model`` The class of the objects that are added to, removed from or cleared @@ -228,6 +240,9 @@ Arguments sent with this signal: For the ``"clear"`` action, this is ``None``. + ``using`` + The database alias being used. + For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled like this: @@ -266,6 +281,8 @@ the arguments sent to a :data:`m2m_changed` handler would be: ``Pizza``) ``pk_set`` ``[t.id]`` (since only ``Topping t`` was added to the relation) + + ``using`` ``"default"`` (since the default router sends writes here) ============== ============================================================ And if we would then do something like this: @@ -293,6 +310,8 @@ the arguments sent to a :data:`m2m_changed` handler would be: ``pk_set`` ``[p.id]`` (since only ``Pizza p`` was removed from the relation) + + ``using`` ``"default"`` (since the default router sends writes here) ============== ============================================================ class_prepared diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 002aa3f416..0cf445cab7 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -1883,6 +1883,8 @@ For example:: If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is ..."``. +Newlines within the string will be removed. + .. templatefilter:: truncatewords_html truncatewords_html @@ -1902,6 +1904,8 @@ For example:: If ``value`` is ``"<p>Joel is a slug</p>"``, the output will be ``"<p>Joel is ...</p>"``. +Newlines in the HTML content will be preserved. + .. templatefilter:: unordered_list unordered_list diff --git a/docs/releases/1.1-beta-1.txt b/docs/releases/1.1-beta-1.txt index a433efc33c..e7dcb4633d 100644 --- a/docs/releases/1.1-beta-1.txt +++ b/docs/releases/1.1-beta-1.txt @@ -71,8 +71,9 @@ processing to convert them to Python objects. If you know you don't need those particular fields, you can now tell Django not to retrieve them from the database. -You'll do this with the :ref:`new queryset methods <queryset-defer>` -``defer()`` and ``only()``. +You'll do this with the new queryset methods +:meth:`~django.db.models.QuerySet.defer` and +:meth:`~django.db.models.QuerySet.only`. New admin features ------------------ @@ -108,13 +109,13 @@ A couple of small but very useful improvements have been made to the * The test :class:`Client` now can automatically follow redirects with the ``follow`` argument to :meth:`Client.get` and :meth:`Client.post`. This makes testing views that issue redirects simpler. - + * It's now easier to get at the template context in the response returned the test client: you'll simply access the context as ``request.context[key]``. The old way, which treats ``request.context`` as a list of contexts, one for each rendered template, is still available if you need it. - + Conditional view processing --------------------------- @@ -133,23 +134,23 @@ release, including: * The :djadmin:`dumpdata` management command now accepts individual model names as arguments, allowing you to export the data just from particular models. - + * There's a new :tfilter:`safeseq` template filter which works just like :tfilter:`safe` for lists, marking each item in the list as safe. - + * :ref:`Cache backends <topics-cache>` now support ``incr()`` and ``decr()`` commands to increment and decrement the value of a cache key. On cache backends that support atomic increment/decrement -- most notably, the memcached backend -- these operations will be atomic, and quite fast. - + * Django now can :ref:`easily delegate authentication to the web server <howto-auth-remote-user>` via a new authentication backend that supports the standard ``REMOTE_USER`` environment variable used for this purpose. - + * There's a new :func:`django.shortcuts.redirect` function that makes it easier to issue redirects given an object, a view name, or a URL. - + * The ``postgresql_psycopg2`` backend now supports :ref:`native PostgreSQL autocommit <postgresql-notes>`. This is an advanced, PostgreSQL-specific feature, that can make certain read-heavy applications a good deal @@ -183,7 +184,7 @@ central place to search for open issues: * http://code.djangoproject.com/timeline Please open new tickets if no existing ticket corresponds to a problem you're -running into. +running into. Additionally, discussion of Django development, including progress toward the 1.1 release, takes place daily on the django-developers mailing list: @@ -195,7 +196,7 @@ interested in helping out with Django's development, feel free to join the discussions there. Django's online documentation also includes pointers on how to contribute to -Django: +Django: * :ref:`How to contribute to Django <internals-contributing>` diff --git a/docs/releases/1.1.txt b/docs/releases/1.1.txt index edb7cf1af2..30ef9197c7 100644 --- a/docs/releases/1.1.txt +++ b/docs/releases/1.1.txt @@ -258,8 +258,9 @@ processing to convert them to Python objects. If you know you don't need those particular fields, you can now tell Django not to retrieve them from the database. -You'll do this with the :ref:`new queryset methods <queryset-defer>` -``defer()`` and ``only()``. +You'll do this with the new queryset methods +:meth:`~django.db.models.QuerySet.defer` and +:meth:`~django.db.models.QuerySet.only`. Testing improvements -------------------- diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index b0d0397055..d64d161aa4 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -18,6 +18,31 @@ fixes and an easy upgrade path from Django 1.2. Backwards-incompatible changes in 1.3 ===================================== +PasswordInput default rendering behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Prior to Django 1.3, a :class:`~django.forms.PasswordInput` would render +data values like any other form. If a form submission raised an error, +the password that was submitted would be reflected to the client as form +data populating the form for resubmission. + +This had the potential to leak passwords, as any failed password +attempt would cause the password that was typed to be sent back to the +client. + +In Django 1.3, the default behavior of +:class:`~django.forms.PasswordInput` is to suppress the display of +password values. This change doesn't alter the way form data is +validated or handled. It only affects the user experience with +passwords on a form when they make an error submitting form data (such +as on unsuccessful logins, or when completing a registration form). + +If you want restore the pre-Django 1.3 behavior, you need to pass in a +custom widget to your form that sets the ``render_value`` argument:: + + class LoginForm(forms.Form): + username = forms.CharField(max_length=100) + password = forms.PasswordField(widget=forms.PasswordInput(render_value=True)) Features deprecated in 1.3 diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt index eae07ed717..480509961b 100644 --- a/docs/topics/auth.txt +++ b/docs/topics/auth.txt @@ -898,8 +898,9 @@ includes a few other useful built-in views located in .. function:: views.password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect]) - Allows a user to reset their password, and sends them the new password - in an e-mail. + Allows a user to reset their password by generating a one-time use link + that can be used to reset the password, and sending that link to the + user's registered e-mail address. **Optional arguments:** @@ -1005,8 +1006,8 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`: .. class:: PasswordResetForm - A form for resetting a user's password and e-mailing the new password to - them. + A form for generating and e-mailing a one-time use link to reset a + user's password. .. class:: SetPasswordForm diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index 9dedbcf3b9..5e263aa543 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -136,6 +136,49 @@ settings file. You can't use a different database backend for your cache table. Database caching works best if you've got a fast, well-indexed database server. +Database caching and multiple databases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you use database caching with multiple databases, you'll also need +to set up routing instructions for your database cache table. For the +purposes of routing, the database cache table appears as a model named +``CacheEntry``, in an application named ``django_cache``. This model +won't appear in the models cache, but the model details can be used +for routing purposes. + +For example, the following router would direct all cache read +operations to ``cache_slave``, and all write operations to +``cache_master``. The cache table will only be synchronized onto +``cache_master``:: + + class CacheRouter(object): + """A router to control all database cache operations""" + + def db_for_read(self, model, **hints): + "All cache read operations go to the slave" + if model._meta.app_label in ('django_cache',): + return 'cache_slave' + return None + + def db_for_write(self, model, **hints): + "All cache write operations go to master" + if model._meta.app_label in ('django_cache',): + return 'cache_master' + return None + + def allow_syncdb(self, db, model): + "Only synchronize the cache model on master" + if model._meta.app_label in ('django_cache',): + return db == 'cache_master' + return None + +If you don't specify routing directions for the database cache model, +the cache backend will use the ``default`` database. + +Of course, if you don't use the database cache backend, you don't need +to worry about providing routing instructions for the database cache +model. + Filesystem caching ------------------ diff --git a/docs/topics/db/aggregation.txt b/docs/topics/db/aggregation.txt index 087c1bf239..41580c94b6 100644 --- a/docs/topics/db/aggregation.txt +++ b/docs/topics/db/aggregation.txt @@ -353,7 +353,7 @@ without any harmful effects, since that is already playing a role in the query. This behavior is the same as that noted in the queryset documentation for -:ref:`distinct() <queryset-distinct>` and the general rule is the same: +:meth:`~django.db.models.QuerySet.distinct` and the general rule is the same: normally you won't want extra columns playing a part in the result, so clear out the ordering, or at least make sure it's restricted only to those fields you also select in a ``values()`` call. diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt index 123408b2bb..aa47e5dd15 100644 --- a/docs/topics/db/managers.txt +++ b/docs/topics/db/managers.txt @@ -170,7 +170,8 @@ and ``Person.people.all()``, yielding predictable results. If you use custom ``Manager`` objects, take note that the first ``Manager`` Django encounters (in the order in which they're defined in the model) has a special status. Django interprets the first ``Manager`` defined in a class as -the "default" ``Manager``, and several parts of Django will use that ``Manager`` +the "default" ``Manager``, and several parts of Django +(including :djadmin:`dumpdata`) will use that ``Manager`` exclusively for that model. As a result, it's a good idea to be careful in your choice of default manager in order to avoid a situation where overriding ``get_query_set()`` results in an inability to retrieve objects you'd like to diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 6d7a7a4374..78c578d61a 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -353,7 +353,7 @@ For example, if a ``Pizza`` has multiple ``Topping`` objects -- that is, a As with :class:`~django.db.models.ForeignKey`, you can also create :ref:`recursive relationships <recursive-relationships>` (an object with a -many-to-one relationship to itself) and :ref:`relationships to models not yet +many-to-many relationship to itself) and :ref:`relationships to models not yet defined <lazy-relationships>`; see :ref:`the model field reference <ref-manytomany>` for details. diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index 5d74fc9ce9..bb40139f23 100644 --- a/docs/topics/db/optimization.txt +++ b/docs/topics/db/optimization.txt @@ -101,7 +101,7 @@ Use ``iterator()`` When you have a lot of objects, the caching behaviour of the ``QuerySet`` can cause a large amount of memory to be used. In this case, -:ref:`QuerySet.iterator() <queryset-iterator>` may help. +:meth:`~django.db.models.QuerySet.iterator()` may help. Do database work in the database rather than in Python ====================================================== @@ -121,9 +121,9 @@ If these aren't enough to generate the SQL you need: Use ``QuerySet.extra()`` ------------------------ -A less portable but more powerful method is :ref:`QuerySet.extra() -<queryset-extra>`, which allows some SQL to be explicitly added to the query. -If that still isn't powerful enough: +A less portable but more powerful method is +:meth:`~django.db.models.QuerySet.extra()`, which allows some SQL to be +explicitly added to the query. If that still isn't powerful enough: Use raw SQL ----------- @@ -159,7 +159,7 @@ Use ``QuerySet.values()`` and ``values_list()`` ----------------------------------------------- When you just want a dict/list of values, and don't need ORM model objects, make -appropriate usage of :ref:`QuerySet.values() <queryset-values>`. +appropriate usage of :meth:`~django.db.models.QuerySet.values()`. These can be useful for replacing model objects in template code - as long as the dicts you supply have the same attributes as those used in the template, you are fine. @@ -167,7 +167,8 @@ are fine. Use ``QuerySet.defer()`` and ``only()`` --------------------------------------- -Use :ref:`defer() and only() <queryset-defer>` if there are database columns you +Use :meth:`~django.db.models.QuerySet.defer()` and +:meth:`~django.db.models.QuerySet.only()` if there are database columns you know that you won't need (or won't need in most cases) to avoid loading them. Note that if you *do* use them, the ORM will have to go and get them in a separate query, making this a pessimization if you use it inappropriately. diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt index f55a164373..c3272da757 100644 --- a/docs/topics/db/sql.txt +++ b/docs/topics/db/sql.txt @@ -116,9 +116,9 @@ Fields may also be left out:: >>> people = Person.objects.raw('SELECT id, first_name FROM myapp_person') -The ``Person`` objects returned by this query will be :ref:`deferred -<queryset-defer>` model instances. This means that the fields that are omitted -from the query will be loaded on demand. For example:: +The ``Person`` objects returned by this query will be deferred model instances +(see :meth:`~django.db.models.QuerySet.defer()`). This means that the fields +that are omitted from the query will be loaded on demand. For example:: >>> for p in Person.objects.raw('SELECT id, first_name FROM myapp_person'): ... print p.first_name, # This will be retrieved by the original query diff --git a/docs/topics/email.txt b/docs/topics/email.txt index 74e153de61..8ea64dac1f 100644 --- a/docs/topics/email.txt +++ b/docs/topics/email.txt @@ -501,7 +501,7 @@ convenience that can be used during development. Defining a custom e-mail backend -------------------------------- -If you need to change how e-mails are send you can write your own e-mail +If you need to change how e-mails are sent you can write your own e-mail backend. The ``EMAIL_BACKEND`` setting in your settings file is then the Python import path for your backend class. diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index fd3edf5104..02cce34fbc 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -595,8 +595,8 @@ Alternatively, you can create a subclass that sets ``self.queryset`` in class BaseAuthorFormSet(BaseModelFormSet): def __init__(self, *args, **kwargs): - self.queryset = Author.objects.filter(name__startswith='O') super(BaseAuthorFormSet, self).__init__(*args, **kwargs) + self.queryset = Author.objects.filter(name__startswith='O') Then, pass your ``BaseAuthorFormSet`` class to the factory function:: diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index 5a2980f9d2..d5746c52f2 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -827,17 +827,80 @@ namespaces into URLs on specific application instances, according to the resolve() --------- -The :func:`django.core.urlresolvers.resolve` function can be used for resolving -URL paths to the corresponding view functions. It has the following signature: +The :func:`django.core.urlresolvers.resolve` function can be used for +resolving URL paths to the corresponding view functions. It has the +following signature: .. function:: resolve(path, urlconf=None) -``path`` is the URL path you want to resolve. As with ``reverse()`` above, you -don't need to worry about the ``urlconf`` parameter. The function returns the -triple (view function, arguments, keyword arguments). +``path`` is the URL path you want to resolve. As with +:func:`~django.core.urlresolvers.reverse`, you don't need to +worry about the ``urlconf`` parameter. The function returns a +:class:`django.core.urlresolvers.ResolverMatch` object that allows you +to access various meta-data about the resolved URL. -For example, it can be used for testing if a view would raise a ``Http404`` -error before redirecting to it:: +.. class:: ResolverMatch() + + .. attribute:: ResolverMatch.func + + The view function that would be used to serve the URL + + .. attribute:: ResolverMatch.args + + The arguments that would be passed to the view function, as + parsed from the URL. + + .. attribute:: ResolverMatch.kwargs + + The keyword arguments that would be passed to the view + function, as parsed from the URL. + + .. attribute:: ResolverMatch.url_name + + The name of the URL pattern that matches the URL. + + .. attribute:: ResolverMatch.app_name + + The application namespace for the URL pattern that matches the + URL. + + .. attribute:: ResolverMatch.namespace + + The instance namespace for the URL pattern that matches the + URL. + + .. attribute:: ResolverMatch.namespaces + + The list of individual namespace components in the full + instance namespace for the URL pattern that matches the URL. + i.e., if the namespace is ``foo:bar``, then namespaces will be + ``[`foo`, `bar`]``. + +A :class:`~django.core.urlresolvers.ResolverMatch` object can then be +interrogated to provide information about the URL pattern that matches +a URL:: + + # Resolve a URL + match = resolve('/some/path/') + # Print the URL pattern that matches the URL + print match.url_name + +A :class:`~django.core.urlresolvers.ResolverMatch` object can also be +assigned to a triple:: + + func, args, kwargs = resolve('/some/path/') + +.. versionchanged:: 1.3 + Triple-assignment exists for backwards-compatibility. Prior to + Django 1.3, :func:`~django.core.urlresolvers.resolve` returned a + triple containing (view function, arguments, keyword arguments); + the :class:`~django.core.urlresolvers.ResolverMatch` object (as + well as the namespace and pattern information it provides) is not + available in earlier Django releases. + +One possible use of :func:`~django.core.urlresolvers.resolve` would be +to testing if a view would raise a ``Http404`` error before +redirecting to it:: from urlparse import urlparse from django.core.urlresolvers import resolve @@ -858,6 +921,7 @@ error before redirecting to it:: return HttpResponseRedirect('/') return response + permalink() ----------- diff --git a/docs/topics/i18n/internationalization.txt b/docs/topics/i18n/internationalization.txt index 7ae8d18791..35e76c3d62 100644 --- a/docs/topics/i18n/internationalization.txt +++ b/docs/topics/i18n/internationalization.txt @@ -569,7 +569,7 @@ function supports both positional and named interpolation: object or associative array. For example:: d = { - count: 10 + count: 10, total: 50 }; diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt index c5155107f0..b99a3b925e 100644 --- a/docs/topics/serialization.txt +++ b/docs/topics/serialization.txt @@ -338,7 +338,7 @@ example, ``(first name, last name)``. Then, when you call ``serializers.serialize()``, you provide a ``use_natural_keys=True`` argument:: - >>> serializers.serialize([book1, book2], format='json', indent=2, use_natural_keys=True) + >>> serializers.serialize('json', [book1, book2], indent=2, use_natural_keys=True) When ``use_natural_keys=True`` is specified, Django will use the ``natural_key()`` method to serialize any reference to objects of the |
