diff options
Diffstat (limited to 'docs')
200 files changed, 2706 insertions, 2171 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..325ed76cdc 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,13 @@ 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 +from sphinx.util.compat import Directive + def setup(app): app.add_crossref_type( @@ -69,63 +56,70 @@ def setup(app): parse_node = parse_django_adminopt_node, ) app.add_config_value('django_next_version', '0.0', True) - app.add_directive('versionadded', parse_version_directive, 1, (1, 1, 1)) - app.add_directive('versionchanged', parse_version_directive, 1, (1, 1, 1)) + app.add_directive('versionadded', VersionDirective) + app.add_directive('versionchanged', VersionDirective) 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() - 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) - node.extend(xrefs[0]) - node['version'] = arguments[0] - else: - node['version'] = "Development version" - node['type'] = name - if len(arguments) == 2: - inodes, messages = state.inline_text(arguments[1], lineno+1) - node.extend(inodes) - if content: - state.nested_parse(content, content_offset, node) - ret = ret + messages - env.note_versionchange(node['type'], node['version'], node, lineno) - return ret - -class SuppressBlockquotes(docutils.transforms.Transform): +class VersionDirective(Directive): + has_content = True + required_arguments = 1 + optional_arguments = 1 + final_argument_whitespace = True + option_spec = {} + + def run(self): + env = self.state.document.settings.env + arg0 = self.arguments[0] + is_nextversion = env.config.django_next_version == arg0 + ret = [] + node = addnodes.versionmodified() + ret.append(node) + if not is_nextversion: + if len(self.arguments) == 1: + linktext = 'Please, see the release notes </releases/%s>' % (arg0) + try: + xrefs = roles.XRefRole()('doc', linktext, linktext, self.lineno, self.state) # Sphinx >= 1.0 + except AttributeError: + xrefs = roles.xfileref_role('doc', linktext, linktext, self.lineno, self.state) # Sphinx < 1.0 + node.extend(xrefs[0]) + node['version'] = arg0 + else: + node['version'] = "Development version" + node['type'] = self.name + if len(self.arguments) == 2: + inodes, messages = self.state.inline_text(self.arguments[1], self.lineno+1) + node.extend(inodes) + if self.content: + self.state.nested_parse(self.content, self.content_offset, node) + ret = ret + messages + env.note_versionchange(node['type'], node['version'], node, self.lineno) + return ret + + +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 +127,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 +171,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 ImportError: + from sphinx.directives.desc import option_desc_re # Sphinx < 1.0 count = 0 firstname = '' for m in option_desc_re.finditer(sig): @@ -228,44 +211,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 +225,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/admin.txt b/docs/faq/admin.txt index ed705d5f21..ac2e594ed2 100644 --- a/docs/faq/admin.txt +++ b/docs/faq/admin.txt @@ -1,5 +1,3 @@ -.. _faq-admin: - FAQ: The admin ============== @@ -32,30 +30,33 @@ How can I prevent the cache middleware from caching the admin site? ------------------------------------------------------------------- Set the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` setting to ``True``. See the -:ref:`cache documentation <topics-cache>` for more information. +:doc:`cache documentation </topics/cache>` for more information. How do I automatically set a field's value to the user who last edited the object in the admin? ----------------------------------------------------------------------------------------------- -The :class:`ModelAdmin` class provides customization hooks that allow you to transform -an object as it saved, using details from the request. By extracting the current user -from the request, and customizing the :meth:`ModelAdmin.save_model` hook, you can update -an object to reflect the user that edited it. See :ref:`the documentation on ModelAdmin -methods <model-admin-methods>` for an example. +The :class:`~django.contrib.admin.ModelAdmin` class provides customization hooks +that allow you to transform an object as it saved, using details from the +request. By extracting the current user from the request, and customizing the +:meth:`~django.contrib.admin.ModelAdmin.save_model` hook, you can update an +object to reflect the user that edited it. See :ref:`the documentation on +ModelAdmin methods <model-admin-methods>` for an example. How do I limit admin access so that objects can only be edited by the users who created them? --------------------------------------------------------------------------------------------- -The :class:`ModelAdmin` class also provides customization hooks that allow you to control the -visibility and editability of objects in the admin. Using the same trick of extracting the -user from the request, the :meth:`ModelAdmin.queryset` and :meth:`ModelAdmin.has_change_permission` -can be used to control the visibility and editability of objects in the admin. +The :class:`~django.contrib.admin.ModelAdmin` class also provides customization +hooks that allow you to control the visibility and editability of objects in the +admin. Using the same trick of extracting the user from the request, the +:meth:`~django.contrib.admin.ModelAdmin.queryset` and +:meth:`~django.contrib.admin.ModelAdmin.has_change_permission` can be used to +control the visibility and editability of objects in the admin. -My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_python. +My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_wsgi. --------------------------------------------------------------------------------------------------------------------------- -See :ref:`serving the admin files <howto-deployment-modpython-serving-the-admin-files>` -in the "How to use Django with mod_python" documentation. +See :ref:`serving the admin files <serving-the-admin-files>` +in the "How to use Django with mod_wsgi" documentation. My "list_filter" contains a ManyToManyField, but the filter doesn't display. ---------------------------------------------------------------------------- @@ -91,5 +92,5 @@ We like it, but if you don't agree, you can modify the admin site's presentation by editing the CSS stylesheet and/or associated image files. The site is built using semantic HTML and plenty of CSS hooks, so any changes you'd like to make should be possible by editing the stylesheet. We've got a -:ref:`guide to the CSS used in the admin <obsolete-admin-css>` to get you started. +:doc:`guide to the CSS used in the admin </obsolete/admin-css>` to get you started. diff --git a/docs/faq/contributing.txt b/docs/faq/contributing.txt index 51a9bc2c6a..81c06f365f 100644 --- a/docs/faq/contributing.txt +++ b/docs/faq/contributing.txt @@ -1,5 +1,3 @@ -.. _faq-contributing: - FAQ: Contributing code ====================== @@ -7,7 +5,7 @@ How can I get started contributing code to Django? -------------------------------------------------- Thanks for asking! We've written an entire document devoted to this question. -It's titled :ref:`Contributing to Django <internals-contributing>`. +It's titled :doc:`Contributing to Django </internals/contributing>`. I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch? -------------------------------------------------------------------------------------------- diff --git a/docs/faq/general.txt b/docs/faq/general.txt index 1181d261be..1fc0f1882a 100644 --- a/docs/faq/general.txt +++ b/docs/faq/general.txt @@ -1,5 +1,3 @@ -.. _faq-general: - FAQ: General ============ @@ -63,15 +61,15 @@ at any level -- database servers, caching servers or Web/application servers. The framework cleanly separates components such as its database layer and application layer. And it ships with a simple-yet-powerful -:ref:`cache framework <topics-cache>`. +:doc:`cache framework </topics/cache>`. Who's behind this? ------------------ Django was originally developed at World Online, the Web department of a newspaper in Lawrence, Kansas, USA. Django's now run by an international team of -volunteers; you can read all about them over at the :ref:`list of committers -<internals-committers>` +volunteers; you can read all about them over at the :doc:`list of committers +</internals/committers>` Which sites use Django? ----------------------- @@ -146,7 +144,7 @@ philosophies 100%. Like we said: We're picky. We've documented our philosophies on the -:ref:`design philosophies page <misc-design-philosophies>`. +:doc:`design philosophies page </misc/design-philosophies>`. Is Django a content-management-system (CMS)? -------------------------------------------- diff --git a/docs/faq/help.txt b/docs/faq/help.txt index 5d7faf6fec..d84b3f529f 100644 --- a/docs/faq/help.txt +++ b/docs/faq/help.txt @@ -1,5 +1,3 @@ -.. _faq-help: - FAQ: Getting Help ================= diff --git a/docs/faq/index.txt b/docs/faq/index.txt index d357a3ebb0..347cabaabc 100644 --- a/docs/faq/index.txt +++ b/docs/faq/index.txt @@ -1,5 +1,3 @@ -.. _faq-index: - ========== Django FAQ ========== diff --git a/docs/faq/install.txt b/docs/faq/install.txt index f20b2bc187..3fbcb3842d 100644 --- a/docs/faq/install.txt +++ b/docs/faq/install.txt @@ -1,5 +1,3 @@ -.. _faq-install: - FAQ: Installation ================= @@ -7,9 +5,9 @@ How do I get started? --------------------- #. `Download the code`_. - #. Install Django (read the :ref:`installation guide <intro-install>`). - #. Walk through the :ref:`tutorial <intro-tutorial01>`. - #. Check out the rest of the :ref:`documentation <index>`, and `ask questions`_ if you + #. Install Django (read the :doc:`installation guide </intro/install>`). + #. Walk through the :doc:`tutorial </intro/tutorial01>`. + #. Check out the rest of the :doc:`documentation </index>`, and `ask questions`_ if you run into trouble. .. _`Download the code`: http://www.djangoproject.com/download/ @@ -19,14 +17,14 @@ 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 -- you don't need to have a separate Web server installed; Django comes with its own lightweight development server. For a production environment, Django follows the WSGI_ spec, which means it can run on a variety of server -platforms. See :ref:`Deploying Django <howto-deployment-index>` for some +platforms. See :doc:`Deploying Django </howto/deployment/index>` for some popular alternatives. Also, the `server arrangements wiki page`_ contains details for several deployment strategies. @@ -46,7 +44,7 @@ Do I lose anything by using Python 2.4 versus newer Python versions, such as Pyt ----------------------------------------------------------------------------------------------- Not in the core framework. Currently, Django itself officially supports any -version of Python from 2.4 through 2.6, inclusive. However, newer versions of +version of Python from 2.4 through 2.7, inclusive. However, newer versions of Python are often faster, have more features, and are better supported. Third-party applications for use with Django are, of course, free to set their own version requirements. @@ -56,7 +54,7 @@ versions as part of a migration which will end with Django running on Python 3 (see below for details). All else being equal, we recommend that you use the latest 2.x release -(currently Python 2.6). This will let you take advantage of the numerous +(currently Python 2.7). This will let you take advantage of the numerous improvements and optimizations to the Python language since version 2.4, and will help ease the process of dropping support for older Python versions on the road to Python 3. diff --git a/docs/faq/models.txt b/docs/faq/models.txt index 2732c0b8e1..f00d453d88 100644 --- a/docs/faq/models.txt +++ b/docs/faq/models.txt @@ -1,5 +1,3 @@ -.. _faq-models: - FAQ: Databases and models ========================= @@ -30,7 +28,7 @@ backend, and not all backends provide a way to retrieve the SQL after quoting. .. versionadded:: 1.2 -If you are using :ref:`multiple databases<topics-db-multi-db>`, you can use the +If you are using :doc:`multiple databases</topics/db/multi-db>`, you can use the same interface on each member of the ``connections`` dictionary:: >>> from django.db import connections @@ -39,7 +37,7 @@ same interface on each member of the ``connections`` dictionary:: Can I use Django with a pre-existing database? ---------------------------------------------- -Yes. See :ref:`Integrating with a legacy database <howto-legacy-databases>`. +Yes. See :doc:`Integrating with a legacy database </howto/legacy-databases>`. If I make changes to a model, how do I update the database? ----------------------------------------------------------- diff --git a/docs/faq/usage.txt b/docs/faq/usage.txt index 6c3c518bb2..856b97c35c 100644 --- a/docs/faq/usage.txt +++ b/docs/faq/usage.txt @@ -1,5 +1,3 @@ -.. _faq-usage: - FAQ: Using Django ================= diff --git a/docs/glossary.txt b/docs/glossary.txt index 67a62ca31a..b8f7a6b904 100644 --- a/docs/glossary.txt +++ b/docs/glossary.txt @@ -9,19 +9,19 @@ Glossary field An attribute on a :term:`model`; a given field usually maps directly to a single database column. - - See :ref:`topics-db-models`. + + See :doc:`/topics/db/models`. generic view A higher-order :term:`view` function that provides an abstract/generic implementation of a common idiom or pattern found in view development. - - See :ref:`ref-generic-views`. + + See :doc:`/ref/generic-views`. model Models store your application's data. - - See :ref:`topics-db-models`. + + See :doc:`/topics/db/models`. MTV See :ref:`mtv`. @@ -41,7 +41,7 @@ Glossary property Also known as "managed attributes", and a feature of Python since version 2.2. From `the property documentation`__: - + Properties are a neat way to implement attributes whose usage resembles attribute access, but whose implementation uses method calls. [...] You @@ -56,26 +56,26 @@ Glossary queryset An object representing some set of rows to be fetched from the database. - - See :ref:`topics-db-queries`. + + See :doc:`/topics/db/queries`. slug A short label for something, containing only letters, numbers, underscores or hyphens. They're generally used in URLs. For example, in a typical blog entry URL: - + .. parsed-literal:: - + http://www.djangoproject.com/weblog/2008/apr/12/**spring**/ - + the last bit (``spring``) is the slug. template A chunk of text that acts as formatting for representing data. A template helps to abstract the presentation of data from the data itself. - - See :ref:`topics-templates`. - + + See :doc:`/topics/templates`. + view - A function responsible for rending a page.
\ No newline at end of file + A function responsible for rending a page. diff --git a/docs/howto/apache-auth.txt b/docs/howto/apache-auth.txt index 8fd3da2612..b3723f92c6 100644 --- a/docs/howto/apache-auth.txt +++ b/docs/howto/apache-auth.txt @@ -1,12 +1,17 @@ -.. _howto-apache-auth: - ========================================================= Authenticating against Django's user database from Apache ========================================================= +.. warning:: + + Support for mod_python has been deprecated within Django. At that + time, this method of authentication will no longer be provided by + Django. The community is welcome to offer its own alternate + solutions using WSGI middleware or other approaches. + Since keeping multiple authentication databases in sync is a common problem when dealing with Apache, you can configuring Apache to authenticate against Django's -:ref:`authentication system <topics-auth>` directly. For example, you +:doc:`authentication system </topics/auth>` directly. For example, you could: * Serve static/media files directly from Apache only to authenticated users. diff --git a/docs/howto/auth-remote-user.txt b/docs/howto/auth-remote-user.txt index f0e83c0ba5..9dbde29e5c 100644 --- a/docs/howto/auth-remote-user.txt +++ b/docs/howto/auth-remote-user.txt @@ -1,5 +1,3 @@ -.. _howto-auth-remote-user: - ==================================== Authentication using ``REMOTE_USER`` ==================================== diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt index 5005feaa80..1b0f32fb3f 100644 --- a/docs/howto/custom-file-storage.txt +++ b/docs/howto/custom-file-storage.txt @@ -1,5 +1,3 @@ -.. _howto-custom-file-storage: - Writing a custom storage system =============================== @@ -37,7 +35,7 @@ You'll need to follow these steps: the ``path()`` method. Your custom storage system may override any of the storage methods explained in -:ref:`ref-files-storage`, but you **must** implement the following methods: +:doc:`/ref/files/storage`, but you **must** implement the following methods: * :meth:`Storage.delete` * :meth:`Storage.exists` @@ -63,7 +61,7 @@ backend storage system. Called by ``Storage.save()``. The ``name`` will already have gone through ``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a -``File`` object itself. +``File`` object itself. Should return the actual name of name of the file saved (usually the ``name`` passed in, but if the storage needs to change the file name return the new name diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt index f8b173cafa..7b25d6bdbe 100644 --- a/docs/howto/custom-management-commands.txt +++ b/docs/howto/custom-management-commands.txt @@ -1,5 +1,3 @@ -.. _howto-custom-management-commands: - ==================================== Writing custom django-admin commands ==================================== @@ -8,9 +6,9 @@ Writing custom django-admin commands Applications can register their own actions with ``manage.py``. For example, you might want to add a ``manage.py`` action for a Django app that you're -distributing. In this document, we will be building a custom ``closepoll`` +distributing. In this document, we will be building a custom ``closepoll`` command for the ``polls`` application from the -:ref:`tutorial<intro-tutorial01>`. +:doc:`tutorial</intro/tutorial01>`. To do this, just add a ``management/commands`` directory to the application. Each Python module in that directory will be auto-discovered and registered as @@ -62,15 +60,22 @@ look like this: poll.opened = False poll.save() - print 'Successfully closed poll "%s"' % poll_id + self.stdout.write('Successfully closed poll "%s"\n' % poll_id) + +.. note:: + When you are using management commands and wish to provide console + output, you should write to ``self.stdout`` and ``self.stderr``, + instead of printing to ``stdout`` and ``stderr`` directly. By + using these proxies, it becomes much easier to test your custom + command. -The new custom command can be called using ``python manage.py closepoll +The new custom command can be called using ``python manage.py closepoll <poll_id>``. The ``handle()`` method takes zero or more ``poll_ids`` and sets ``poll.opened`` to ``False`` for each one. If the user referenced any nonexistant polls, a :class:`CommandError` is raised. The ``poll.opened`` attribute does not exist -in the :ref:`tutorial<intro-tutorial01>` and was added to +in the :doc:`tutorial</intro/tutorial01>` and was added to ``polls.models.Poll`` for this example. The same ``closepoll`` could be easily modified to delete a given poll instead @@ -91,8 +96,8 @@ must be added to :attr:`~BaseCommand.option_list` like this: ) # ... -In addition to being able to add custom command line options, all -:ref:`management commands<ref-django-admin>` can accept some +In addition to being able to add custom command line options, all +:doc:`management commands</ref/django-admin>` can accept some default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`. Command objects @@ -113,7 +118,7 @@ Subclassing the :class:`BaseCommand` class requires that you implement the Attributes ---------- -All attributes can be set in your derived class and can be used in +All attributes can be set in your derived class and can be used in :class:`BaseCommand`'s :ref:`subclasses<ref-basecommand-subclasses>`. .. attribute:: BaseCommand.args @@ -133,7 +138,7 @@ All attributes can be set in your derived class and can be used in .. attribute:: BaseCommand.help A short description of the command, which will be printed in the - help message when the user runs the command + help message when the user runs the command ``python manage.py help <command>``. .. attribute:: BaseCommand.option_list @@ -230,7 +235,7 @@ Rather than implementing :meth:`~BaseCommand.handle`, subclasses must implement A command which takes no arguments on the command line. Rather than implementing :meth:`~BaseCommand.handle`, subclasses must implement -:meth:`~NoArgsCommand.handle_noargs`; :meth:`~BaseCommand.handle` itself is +:meth:`~NoArgsCommand.handle_noargs`; :meth:`~BaseCommand.handle` itself is overridden to ensure no arguments are passed to the command. .. method:: NoArgsCommand.handle_noargs(**options) diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 90851459c1..fa4c07fed2 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -1,5 +1,3 @@ -.. _howto-custom-model-fields: - =========================== Writing custom model fields =========================== @@ -10,7 +8,7 @@ Writing custom model fields Introduction ============ -The :ref:`model reference <topics-db-models>` documentation explains how to use +The :doc:`model reference </topics/db/models>` documentation explains how to use Django's standard field classes -- :class:`~django.db.models.CharField`, :class:`~django.db.models.DateField`, etc. For many purposes, those classes are all you'll need. Sometimes, though, the Django version won't meet your precise @@ -109,7 +107,7 @@ What does a field class do? --------------------------- All of Django's fields (and when we say *fields* in this document, we always -mean model fields and not :ref:`form fields <ref-forms-fields>`) are subclasses +mean model fields and not :doc:`form fields </ref/forms/fields>`) are subclasses of :class:`django.db.models.Field`. Most of the information that Django records about a field is common to all fields -- name, help text, uniqueness and so forth. Storing all that information is handled by ``Field``. We'll get into the @@ -124,7 +122,7 @@ when the model class is created (the precise details of how this is done are unimportant here). This is because the field classes aren't necessary when you're just creating and modifying attributes. Instead, they provide the machinery for converting between the attribute value and what is stored in the -database or sent to the :ref:`serializer <topics-serialization>`. +database or sent to the :doc:`serializer </topics/serialization>`. Keep this in mind when creating your own custom fields. The Django ``Field`` subclass you write provides the machinery for converting between your Python @@ -209,8 +207,8 @@ parameters: * :attr:`~django.db.models.Field.default` * :attr:`~django.db.models.Field.editable` * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will - not be serialized when the model is passed to Django's :ref:`serializers - <topics-serialization>`. Defaults to ``True``. + not be serialized when the model is passed to Django's :doc:`serializers + </topics/serialization>`. Defaults to ``True``. * :attr:`~django.db.models.Field.unique_for_date` * :attr:`~django.db.models.Field.unique_for_month` * :attr:`~django.db.models.Field.unique_for_year` @@ -225,8 +223,8 @@ parameters: inheritance. For advanced use only. All of the options without an explanation in the above list have the same -meaning they do for normal Django fields. See the :ref:`field documentation -<ref-models-fields>` for examples and details. +meaning they do for normal Django fields. See the :doc:`field documentation +</ref/models/fields>` for examples and details. The ``SubfieldBase`` metaclass ------------------------------ @@ -270,8 +268,8 @@ value. This means that whenever a value may be assigned to the field, you need to ensure that it will be of the correct datatype, or that you handle any exceptions. -This is especially important if you use :ref:`ModelForms -<topics-forms-modelforms>`. When saving a ModelForm, Django will use +This is especially important if you use :doc:`ModelForms +</topics/forms/modelforms>`. When saving a ModelForm, Django will use form values to instantiate model instances. However, if the cleaned form data can't be used as valid input to the field, the normal form validation process will break. @@ -611,8 +609,8 @@ All of the ``kwargs`` dictionary is passed directly to the form field's :meth:`~django.forms.Field__init__` method. Normally, all you need to do is set up a good default for the ``form_class`` argument and then delegate further handling to the parent class. This might require you to write a custom form -field (and even a form widget). See the :ref:`forms documentation -<topics-forms-index>` for information about this, and take a look at the code in +field (and even a form widget). See the :doc:`forms documentation +</topics/forms/index>` for information about this, and take a look at the code in :mod:`django.contrib.localflavor` for some examples of custom widgets. Continuing our ongoing example, we can write the :meth:`formfield` method as:: @@ -721,7 +719,7 @@ Django provides a ``File`` class, which is used as a proxy to the file's contents and operations. This can be subclassed to customize how the file is accessed, and what methods are available. It lives at ``django.db.models.fields.files``, and its default behavior is explained in the -:ref:`file documentation <ref-files-file>`. +:doc:`file documentation </ref/files/file>`. Once a subclass of ``File`` is created, the new ``FileField`` subclass must be told to use it. To do so, simply assign the new ``File`` subclass to the special diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index 1406d19b58..c4d2315bd4 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -1,5 +1,3 @@ -.. _howto-custom-template-tags: - ================================ Custom template tags and filters ================================ @@ -7,8 +5,8 @@ Custom template tags and filters Introduction ============ -Django's template system comes with a wide variety of :ref:`built-in -tags and filters <ref-templates-builtins>` designed to address the +Django's template system comes with a wide variety of :doc:`built-in +tags and filters </ref/templates/builtins>` designed to address the presentation logic needs of your application. Nevertheless, you may find yourself needing functionality that is not covered by the core set of template primitives. You can extend the template engine by diff --git a/docs/howto/deployment/fastcgi.txt b/docs/howto/deployment/fastcgi.txt index cf05174390..c2b8aa8b53 100644 --- a/docs/howto/deployment/fastcgi.txt +++ b/docs/howto/deployment/fastcgi.txt @@ -1,13 +1,11 @@ -.. _howto-deployment-fastcgi: - ============================================ How to use Django with FastCGI, SCGI, or AJP ============================================ .. highlight:: bash -Although the current preferred setup for running Django is :ref:`Apache with -mod_wsgi <howto-deployment-modwsgi>`, many people use shared hosting, on +Although the current preferred setup for running Django is :doc:`Apache with +mod_wsgi </howto/deployment/modwsgi>`, many people use shared hosting, on which protocols such as FastCGI, SCGI or AJP are the only viable options. In some setups, these protocols may provide better performance than mod_wsgi_. @@ -22,14 +20,14 @@ serve pages to a Web server. The Web server delegates the incoming Web requests (via a socket) to FastCGI, which executes the code and passes the response back to the Web server, which, in turn, passes it back to the client's Web browser. -Like mod_python, FastCGI allows code to stay in memory, allowing requests to be -served with no startup time. Unlike mod_python_ (or `mod_perl`_), a FastCGI -process doesn't run inside the Web server process, but in a separate, +Like mod_wsgi, FastCGI allows code to stay in memory, allowing requests to be +served with no startup time. While mod_wsgi can either be configured embedded +in the Apache webserver process or as a separate daemon process, a FastCGI +process never runs inside the Web server process, always in a separate, persistent process. .. _mod_wsgi: http://code.google.com/p/modwsgi/ .. _mod_perl: http://perl.apache.org/ -.. _mod_python: http://www.modpython.org/ .. admonition:: Why run code in a separate process? @@ -37,8 +35,7 @@ persistent process. languages (most notably PHP, Python and Perl) inside the process space of your Web server. Although this lowers startup time -- because code doesn't have to be read off disk for every request -- it comes at the cost of - memory use. For mod_python, for example, every Apache process gets its own - Python interpreter, which uses up a considerable amount of RAM. + memory use. Due to the nature of FastCGI, it's even possible to have processes that run under a different user account than the Web server process. That's a nice @@ -74,7 +71,7 @@ TCP socket. What you choose is a manner of preference; a TCP socket is usually easier due to permissions issues. To start your server, first change into the directory of your project (wherever -your :ref:`manage.py <ref-django-admin>` is), and then run the +your :doc:`manage.py </ref/django-admin>` is), and then run the :djadmin:`runfcgi` command:: ./manage.py runfcgi [options] @@ -363,7 +360,7 @@ Serving admin media files Regardless of the server and configuration you eventually decide to use, you will also need to give some thought to how to serve the admin media files. The -advice given in the :ref:`modpython <serving-the-admin-files>` documentation +advice given in the :ref:`mod_wsgi <serving-the-admin-files>` documentation is also applicable in the setups detailed above. Forcing the URL prefix to a particular value diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt index 78cfb037f5..2eff3e6ace 100644 --- a/docs/howto/deployment/index.txt +++ b/docs/howto/deployment/index.txt @@ -1,5 +1,3 @@ -.. _howto-deployment-index: - Deploying Django ================ @@ -10,18 +8,18 @@ ways to easily deploy Django: .. toctree:: :maxdepth: 1 - + modwsgi - modpython fastcgi - + mod_python (deprecated) <modpython> + If you're new to deploying Django and/or Python, we'd recommend you try -:ref:`mod_wsgi <howto-deployment-modwsgi>` first. In most cases it'll be the easiest, +:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be the easiest, fastest, and most stable deployment choice. .. seealso:: * `Chapter 12 of The Django Book`_ discusses deployment and especially scaling in more detail. - + .. _chapter 12 of the django book: http://djangobook.com/en/2.0/chapter12/ diff --git a/docs/howto/deployment/modpython.txt b/docs/howto/deployment/modpython.txt index 143a6d5ae3..a9b665f331 100644 --- a/docs/howto/deployment/modpython.txt +++ b/docs/howto/deployment/modpython.txt @@ -4,11 +4,18 @@ How to use Django with Apache and mod_python ============================================ +.. warning:: + + Support for mod_python will be deprecated in a future release of Django. If + you are configuring a new deployment, you are strongly encouraged to + consider using :doc:`mod_wsgi </howto/deployment/modwsgi>` or any of the + other :doc:`supported backends </howto/deployment/index>`. + .. highlight:: apache The `mod_python`_ module for Apache_ can be used to deploy Django to a production server, although it has been mostly superseded by the simpler -:ref:`mod_wsgi deployment option <howto-deployment-modwsgi>`. +:doc:`mod_wsgi deployment option </howto/deployment/modwsgi>`. mod_python is similar to (and inspired by) `mod_perl`_ : It embeds Python within Apache and loads Python code into memory when the server starts. Code stays in @@ -25,8 +32,8 @@ Django requires Apache 2.x and mod_python 3.x, and you should use Apache's Apache, there's no better source than `Apache's own official documentation`_ - * You may also be interested in :ref:`How to use Django with FastCGI, SCGI, - or AJP <howto-deployment-fastcgi>`. + * You may also be interested in :doc:`How to use Django with FastCGI, SCGI, + or AJP </howto/deployment/fastcgi>`. .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ @@ -216,8 +223,6 @@ Or add the debugging information to the template of your page. .. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html -.. _serving-media-files: - Serving media files =================== @@ -269,10 +274,6 @@ the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or .. _Apache: http://httpd.apache.org/ .. _Cherokee: http://www.cherokee-project.com/ -.. _howto-deployment-modpython-serving-the-admin-files: - -.. _serving-the-admin-files: - Serving the admin files ======================= @@ -383,7 +384,7 @@ If you get a UnicodeEncodeError =============================== If you're taking advantage of the internationalization features of Django (see -:ref:`topics-i18n`) and you intend to allow users to upload files, you must +:doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must ensure that the environment used to start Apache is configured to accept non-ASCII file names. If your environment is not correctly configured, you will trigger ``UnicodeEncodeError`` exceptions when calling functions like diff --git a/docs/howto/deployment/modwsgi.txt b/docs/howto/deployment/modwsgi.txt index 12de53f53d..e873006af0 100644 --- a/docs/howto/deployment/modwsgi.txt +++ b/docs/howto/deployment/modwsgi.txt @@ -1,5 +1,3 @@ -.. _howto-deployment-modwsgi: - ========================================== How to use Django with Apache and mod_wsgi ========================================== @@ -55,6 +53,8 @@ just above the final ``import`` line to place your project on the path. Remember replace 'mysite.settings' with your correct settings file, and '/usr/local/django' with your own project's location. +.. _serving-media-files: + Serving media files =================== @@ -108,6 +108,29 @@ in the mod_wsgi documentation on `hosting static files`_. .. _hosting static files: http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#Hosting_Of_Static_Files +.. _serving-the-admin-files: + +Serving the admin files +======================= + +Note that the Django development server automagically serves admin media files, +but this is not the case when you use any other server arrangement. You're +responsible for setting up Apache, or whichever media server you're using, to +serve the admin files. + +The admin files live in (:file:`django/contrib/admin/media`) of the Django +distribution. + +Here are two recommended approaches: + + 1. Create a symbolic link to the admin media files from within your + document root. This way, all of your Django-related files -- code **and** + templates -- stay in one place, and you'll still be able to ``svn + update`` your code to get the latest admin templates, if they change. + + 2. Or, copy the admin media files so that they live within your Apache + document root. + Details ======= diff --git a/docs/howto/error-reporting.txt b/docs/howto/error-reporting.txt index 97842d7263..1ec009dd2a 100644 --- a/docs/howto/error-reporting.txt +++ b/docs/howto/error-reporting.txt @@ -1,5 +1,3 @@ -.. _howto-error-reporting: - Error reporting via e-mail ========================== @@ -30,8 +28,8 @@ the HTTP request that caused the error. to specify :setting:`EMAIL_HOST` and possibly :setting:`EMAIL_HOST_USER` and :setting:`EMAIL_HOST_PASSWORD`, though other settings may be also required depending on your mail - server's configuration. Consult :ref:`the Django settings - documentation <ref-settings>` for a full list of email-related + server's configuration. Consult :doc:`the Django settings + documentation </ref/settings>` for a full list of email-related settings. By default, Django will send email from root@localhost. However, some mail diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index 853162aa70..6bec531177 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -1,5 +1,3 @@ -.. _howto-i18n: - .. _using-translations-in-your-own-projects: =============================================== @@ -46,7 +44,7 @@ To create message files, you use the :djadmin:`django-admin.py makemessages <mak tool. You only need to be in the same directory where the ``locale/`` directory is located. And you use :djadmin:`django-admin.py compilemessages <compilemessages>` to produce the binary ``.mo`` files that are used by ``gettext``. Read the -:ref:`topics-i18n-localization` document for more details. +:doc:`/topics/i18n/localization` document for more details. You can also run ``django-admin.py compilemessages --settings=path.to.settings`` to make the compiler process all the directories in your :setting:`LOCALE_PATHS` diff --git a/docs/howto/index.txt b/docs/howto/index.txt index c582c8ed17..49d0644034 100644 --- a/docs/howto/index.txt +++ b/docs/howto/index.txt @@ -1,11 +1,9 @@ -.. _howto-index: - "How-to" guides =============== Here you'll find short answers to "How do I....?" types of questions. These how-to guides don't cover topics in depth -- you'll find that material in the -:ref:`topics-index` and the :ref:`ref-index`. However, these guides will help +:doc:`/topics/index` and the :doc:`/ref/index`. However, these guides will help you quickly accomplish common tasks. .. toctree:: diff --git a/docs/howto/initial-data.txt b/docs/howto/initial-data.txt index b071d6d529..cf3f65d299 100644 --- a/docs/howto/initial-data.txt +++ b/docs/howto/initial-data.txt @@ -1,5 +1,3 @@ -.. _howto-initial-data: - ================================= Providing initial data for models ================================= @@ -20,10 +18,10 @@ Providing initial data with fixtures A fixture is a collection of data that Django knows how to import into a database. The most straightforward way of creating a fixture if you've already -got some data is to use the :djadmin:`manage.py dumpdata` command. Or, you can -write fixtures by hand; fixtures can be written as XML, YAML, or JSON documents. -The :ref:`serialization documentation <topics-serialization>` has more details -about each of these supported :ref:`serialization formats +got some data is to use the :djadmin:`manage.py dumpdata <dumpdata>` command. +Or, you can write fixtures by hand; fixtures can be written as XML, YAML, or +JSON documents. The :doc:`serialization documentation </topics/serialization>` +has more details about each of these supported :ref:`serialization formats <serialization-formats>`. As an example, though, here's what a fixture for a simple ``Person`` model might @@ -114,9 +112,9 @@ which will insert the desired data (e.g., properly-formatted ``INSERT`` statements separated by semicolons). The SQL files are read by the :djadmin:`sqlcustom`, :djadmin:`sqlreset`, -:djadmin:`sqlall` and :djadmin:`reset` commands in :ref:`manage.py -<ref-django-admin>`. Refer to the :ref:`manage.py documentation -<ref-django-admin>` for more information. +:djadmin:`sqlall` and :djadmin:`reset` commands in :doc:`manage.py +</ref/django-admin>`. Refer to the :doc:`manage.py documentation +</ref/django-admin>` for more information. Note that if you have multiple SQL data files, there's no guarantee of the order in which they're executed. The only thing you can assume is diff --git a/docs/howto/jython.txt b/docs/howto/jython.txt index 385790e9e6..673c9360bd 100644 --- a/docs/howto/jython.txt +++ b/docs/howto/jython.txt @@ -1,5 +1,3 @@ -.. _howto-jython: - ======================== Running Django on Jython ======================== diff --git a/docs/howto/legacy-databases.txt b/docs/howto/legacy-databases.txt index b2aa7e4ea6..2121871fa2 100644 --- a/docs/howto/legacy-databases.txt +++ b/docs/howto/legacy-databases.txt @@ -1,5 +1,3 @@ -.. _howto-legacy-databases: - ========================================= Integrating Django with a legacy database ========================================= @@ -9,7 +7,7 @@ possible to integrate it into legacy databases. Django includes a couple of utilities to automate as much of this process as possible. This document assumes you know the Django basics, as covered in the -:ref:`tutorial <intro-tutorial01>`. +:doc:`tutorial </intro/tutorial01>`. Once you've got Django set up, you'll follow this general process to integrate with an existing database. diff --git a/docs/howto/outputting-csv.txt b/docs/howto/outputting-csv.txt index 234454c265..169114ff95 100644 --- a/docs/howto/outputting-csv.txt +++ b/docs/howto/outputting-csv.txt @@ -1,5 +1,3 @@ -.. _howto-outputting-csv: - ========================== Outputting CSV with Django ========================== @@ -61,7 +59,7 @@ mention: Using the template system ========================= -Alternatively, you can use the :ref:`Django template system <topics-templates>` +Alternatively, you can use the :doc:`Django template system </topics/templates>` to generate CSV. This is lower-level than using the convenient CSV, but the solution is presented here for completeness. @@ -113,4 +111,4 @@ Other text-based formats Notice that there isn't very much specific to CSV here -- just the specific output format. You can use either of these techniques to output any text-based format you can dream of. You can also use a similar technique to generate -arbitrary binary data; see :ref:`howto-outputting-pdf` for an example. +arbitrary binary data; see :doc:`/howto/outputting-pdf` for an example. diff --git a/docs/howto/outputting-pdf.txt b/docs/howto/outputting-pdf.txt index 94acab8311..32e38aebc6 100644 --- a/docs/howto/outputting-pdf.txt +++ b/docs/howto/outputting-pdf.txt @@ -1,5 +1,3 @@ -.. _howto-outputting-pdf: - =========================== Outputting PDFs with Django =========================== @@ -154,5 +152,5 @@ Other formats Notice that there isn't a lot in these examples that's PDF-specific -- just the bits using ``reportlab``. You can use a similar technique to generate any arbitrary format that you can find a Python library for. Also see -:ref:`howto-outputting-csv` for another example and some techniques you can use +:doc:`/howto/outputting-csv` for another example and some techniques you can use when generated text-based formats. diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt index f93a4e9ba4..209cf38c36 100644 --- a/docs/howto/static-files.txt +++ b/docs/howto/static-files.txt @@ -1,5 +1,3 @@ -.. _howto-static-files: - ========================= How to serve static files ========================= @@ -33,7 +31,7 @@ Using this method is **inefficient** and **insecure**. Do not use this in a production setting. Use this only for development. For information on serving static files in an Apache production environment, -see the :ref:`Django mod_python documentation <serving-media-files>`. +see the :ref:`Django mod_wsgi documentation <serving-media-files>`. How to do it ============ @@ -42,7 +40,7 @@ Here's the formal definition of the :func:`~django.views.static.serve` view: .. function:: def serve(request, path, document_root, show_indexes=False) -To use it, just put this in your :ref:`URLconf <topics-http-urls>`:: +To use it, just put this in your :doc:`URLconf </topics/http/urls>`:: (r'^site_media/(?P<path>.*)$', 'django.views.static.serve', {'document_root': '/path/to/media'}), @@ -71,7 +69,7 @@ required. For example, if we have a line in ``settings.py`` that says:: STATIC_DOC_ROOT = '/path/to/media' -...we could write the above :ref:`URLconf <topics-http-urls>` entry as:: +...we could write the above :doc:`URLconf </topics/http/urls>` entry as:: from django.conf import settings ... diff --git a/docs/index.txt b/docs/index.txt index aae2e27cb6..c031b03f54 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -12,10 +12,10 @@ Getting help Having trouble? We'd like to help! -* Try the :ref:`FAQ <faq-index>` -- it's got answers to many common questions. +* Try the :doc:`FAQ <faq/index>` -- it's got answers to many common questions. * Looking for specific information? Try the :ref:`genindex`, :ref:`modindex` or - the :ref:`detailed table of contents <contents>`. + the :doc:`detailed table of contents <contents>`. * Search for information in the `archives of the django-users mailing list`_, or `post a question`_. @@ -35,179 +35,179 @@ First steps =========== * **From scratch:** - :ref:`Overview <intro-overview>` | - :ref:`Installation <intro-install>` + :doc:`Overview <intro/overview>` | + :doc:`Installation <intro/install>` * **Tutorial:** - :ref:`Part 1 <intro-tutorial01>` | - :ref:`Part 2 <intro-tutorial02>` | - :ref:`Part 3 <intro-tutorial03>` | - :ref:`Part 4 <intro-tutorial04>` + :doc:`Part 1 <intro/tutorial01>` | + :doc:`Part 2 <intro/tutorial02>` | + :doc:`Part 3 <intro/tutorial03>` | + :doc:`Part 4 <intro/tutorial04>` The model layer =============== * **Models:** - :ref:`Model syntax <topics-db-models>` | - :ref:`Field types <ref-models-fields>` | - :ref:`Meta options <ref-models-options>` + :doc:`Model syntax <topics/db/models>` | + :doc:`Field types <ref/models/fields>` | + :doc:`Meta options <ref/models/options>` * **QuerySets:** - :ref:`Executing queries <topics-db-queries>` | - :ref:`QuerySet method reference <ref-models-querysets>` + :doc:`Executing queries <topics/db/queries>` | + :doc:`QuerySet method reference <ref/models/querysets>` * **Model instances:** - :ref:`Instance methods <ref-models-instances>` | - :ref:`Accessing related objects <ref-models-relations>` + :doc:`Instance methods <ref/models/instances>` | + :doc:`Accessing related objects <ref/models/relations>` * **Advanced:** - :ref:`Managers <topics-db-managers>` | - :ref:`Raw SQL <topics-db-sql>` | - :ref:`Transactions <topics-db-transactions>` | - :ref:`Aggregation <topics-db-aggregation>` | - :ref:`Custom fields <howto-custom-model-fields>` | - :ref:`Multiple databases <topics-db-multi-db>` + :doc:`Managers <topics/db/managers>` | + :doc:`Raw SQL <topics/db/sql>` | + :doc:`Transactions <topics/db/transactions>` | + :doc:`Aggregation <topics/db/aggregation>` | + :doc:`Custom fields <howto/custom-model-fields>` | + :doc:`Multiple databases <topics/db/multi-db>` * **Other:** - :ref:`Supported databases <ref-databases>` | - :ref:`Legacy databases <howto-legacy-databases>` | - :ref:`Providing initial data <howto-initial-data>` | - :ref:`Optimize database access <topics-db-optimization>` + :doc:`Supported databases <ref/databases>` | + :doc:`Legacy databases <howto/legacy-databases>` | + :doc:`Providing initial data <howto/initial-data>` | + :doc:`Optimize database access <topics/db/optimization>` The template layer ================== * **For designers:** - :ref:`Syntax overview <topics-templates>` | - :ref:`Built-in tags and filters <ref-templates-builtins>` + :doc:`Syntax overview <topics/templates>` | + :doc:`Built-in tags and filters <ref/templates/builtins>` * **For programmers:** - :ref:`Template API <ref-templates-api>` | - :ref:`Custom tags and filters <howto-custom-template-tags>` + :doc:`Template API <ref/templates/api>` | + :doc:`Custom tags and filters <howto/custom-template-tags>` The view layer ============== * **The basics:** - :ref:`URLconfs <topics-http-urls>` | - :ref:`View functions <topics-http-views>` | - :ref:`Shortcuts <topics-http-shortcuts>` + :doc:`URLconfs <topics/http/urls>` | + :doc:`View functions <topics/http/views>` | + :doc:`Shortcuts <topics/http/shortcuts>` - * **Reference:** :ref:`Request/response objects <ref-request-response>` + * **Reference:** :doc:`Request/response objects <ref/request-response>` * **File uploads:** - :ref:`Overview <topics-http-file-uploads>` | - :ref:`File objects <ref-files-file>` | - :ref:`Storage API <ref-files-storage>` | - :ref:`Managing files <topics-files>` | - :ref:`Custom storage <howto-custom-file-storage>` + :doc:`Overview <topics/http/file-uploads>` | + :doc:`File objects <ref/files/file>` | + :doc:`Storage API <ref/files/storage>` | + :doc:`Managing files <topics/files>` | + :doc:`Custom storage <howto/custom-file-storage>` * **Generic views:** - :ref:`Overview<topics-generic-views>` | - :ref:`Built-in generic views<ref-generic-views>` + :doc:`Overview<topics/generic-views>` | + :doc:`Built-in generic views<ref/generic-views>` * **Advanced:** - :ref:`Generating CSV <howto-outputting-csv>` | - :ref:`Generating PDF <howto-outputting-pdf>` + :doc:`Generating CSV <howto/outputting-csv>` | + :doc:`Generating PDF <howto/outputting-pdf>` * **Middleware:** - :ref:`Overview <topics-http-middleware>` | - :ref:`Built-in middleware classes <ref-middleware>` + :doc:`Overview <topics/http/middleware>` | + :doc:`Built-in middleware classes <ref/middleware>` Forms ===== * **The basics:** - :ref:`Overview <topics-forms-index>` | - :ref:`Form API <ref-forms-api>` | - :ref:`Built-in fields <ref-forms-fields>` | - :ref:`Built-in widgets <ref-forms-widgets>` + :doc:`Overview <topics/forms/index>` | + :doc:`Form API <ref/forms/api>` | + :doc:`Built-in fields <ref/forms/fields>` | + :doc:`Built-in widgets <ref/forms/widgets>` * **Advanced:** - :ref:`Forms for models <topics-forms-modelforms>` | - :ref:`Integrating media <topics-forms-media>` | - :ref:`Formsets <topics-forms-formsets>` | - :ref:`Customizing validation <ref-forms-validation>` + :doc:`Forms for models <topics/forms/modelforms>` | + :doc:`Integrating media <topics/forms/media>` | + :doc:`Formsets <topics/forms/formsets>` | + :doc:`Customizing validation <ref/forms/validation>` * **Extras:** - :ref:`Form preview <ref-contrib-formtools-form-preview>` | - :ref:`Form wizard <ref-contrib-formtools-form-wizard>` + :doc:`Form preview <ref/contrib/formtools/form-preview>` | + :doc:`Form wizard <ref/contrib/formtools/form-wizard>` The development process ======================= * **Settings:** - :ref:`Overview <topics-settings>` | - :ref:`Full list of settings <ref-settings>` + :doc:`Overview <topics/settings>` | + :doc:`Full list of settings <ref/settings>` * **Exceptions:** - :ref:`Overview <ref-exceptions>` + :doc:`Overview <ref/exceptions>` * **django-admin.py and manage.py:** - :ref:`Overview <ref-django-admin>` | - :ref:`Adding custom commands <howto-custom-management-commands>` + :doc:`Overview <ref/django-admin>` | + :doc:`Adding custom commands <howto/custom-management-commands>` - * **Testing:** :ref:`Overview <topics-testing>` + * **Testing:** :doc:`Overview <topics/testing>` * **Deployment:** - :ref:`Overview <howto-deployment-index>` | - :ref:`Apache/mod_wsgi <howto-deployment-modwsgi>` | - :ref:`Apache/mod_python <howto-deployment-modpython>` | - :ref:`FastCGI/SCGI/AJP <howto-deployment-fastcgi>` | - :ref:`Apache authentication <howto-apache-auth>` | - :ref:`Serving static files <howto-static-files>` | - :ref:`Tracking code errors by e-mail <howto-error-reporting>` + :doc:`Overview <howto/deployment/index>` | + :doc:`Apache/mod_wsgi <howto/deployment/modwsgi>` | + :doc:`Apache/mod_python <howto/deployment/modpython>` | + :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` | + :doc:`Apache authentication <howto/apache-auth>` | + :doc:`Serving static files <howto/static-files>` | + :doc:`Tracking code errors by e-mail <howto/error-reporting>` Other batteries included ======================== - * :ref:`Admin site <ref-contrib-admin>` | :ref:`Admin actions <ref-contrib-admin-actions>` - * :ref:`Authentication <topics-auth>` - * :ref:`Cache system <topics-cache>` - * :ref:`Conditional content processing <topics-conditional-processing>` - * :ref:`Comments <ref-contrib-comments-index>` | :ref:`Moderation <ref-contrib-comments-moderation>` | :ref:`Custom comments <ref-contrib-comments-custom>` - * :ref:`Content types <ref-contrib-contenttypes>` - * :ref:`Cross Site Request Forgery protection <ref-contrib-csrf>` - * :ref:`Databrowse <ref-contrib-databrowse>` - * :ref:`E-mail (sending) <topics-email>` - * :ref:`Flatpages <ref-contrib-flatpages>` - * :ref:`GeoDjango <ref-contrib-gis>` - * :ref:`Humanize <ref-contrib-humanize>` - * :ref:`Internationalization <topics-i18n>` - * :ref:`Jython support <howto-jython>` - * :ref:`"Local flavor" <ref-contrib-localflavor>` - * :ref:`Messages <ref-contrib-messages>` - * :ref:`Pagination <topics-pagination>` - * :ref:`Redirects <ref-contrib-redirects>` - * :ref:`Serialization <topics-serialization>` - * :ref:`Sessions <topics-http-sessions>` - * :ref:`Signals <topics-signals>` - * :ref:`Sitemaps <ref-contrib-sitemaps>` - * :ref:`Sites <ref-contrib-sites>` - * :ref:`Syndication feeds (RSS/Atom) <ref-contrib-syndication>` - * :ref:`Unicode in Django <ref-unicode>` - * :ref:`Web design helpers <ref-contrib-webdesign>` - * :ref:`Validators <ref-validators>` + * :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>` + * :doc:`Authentication <topics/auth>` + * :doc:`Cache system <topics/cache>` + * :doc:`Conditional content processing <topics/conditional-view-processing>` + * :doc:`Comments <ref/contrib/comments/index>` | :doc:`Moderation <ref/contrib/comments/moderation>` | :doc:`Custom comments <ref/contrib/comments/custom>` + * :doc:`Content types <ref/contrib/contenttypes>` + * :doc:`Cross Site Request Forgery protection <ref/contrib/csrf>` + * :doc:`Databrowse <ref/contrib/databrowse>` + * :doc:`E-mail (sending) <topics/email>` + * :doc:`Flatpages <ref/contrib/flatpages>` + * :doc:`GeoDjango <ref/contrib/gis/index>` + * :doc:`Humanize <ref/contrib/humanize>` + * :doc:`Internationalization <topics/i18n/index>` + * :doc:`Jython support <howto/jython>` + * :doc:`"Local flavor" <ref/contrib/localflavor>` + * :doc:`Messages <ref/contrib/messages>` + * :doc:`Pagination <topics/pagination>` + * :doc:`Redirects <ref/contrib/redirects>` + * :doc:`Serialization <topics/serialization>` + * :doc:`Sessions <topics/http/sessions>` + * :doc:`Signals <topics/signals>` + * :doc:`Sitemaps <ref/contrib/sitemaps>` + * :doc:`Sites <ref/contrib/sites>` + * :doc:`Syndication feeds (RSS/Atom) <ref/contrib/syndication>` + * :doc:`Unicode in Django <ref/unicode>` + * :doc:`Web design helpers <ref/contrib/webdesign>` + * :doc:`Validators <ref/validators>` The Django open-source project ============================== * **Community:** - :ref:`How to get involved <internals-contributing>` | - :ref:`The release process <internals-release-process>` | - :ref:`Team of committers <internals-committers>` | - :ref:`The Django source code repository <internals-svn>` + :doc:`How to get involved <internals/contributing>` | + :doc:`The release process <internals/release-process>` | + :doc:`Team of committers <internals/committers>` | + :doc:`The Django source code repository <internals/svn>` * **Design philosophies:** - :ref:`Overview <misc-design-philosophies>` + :doc:`Overview <misc/design-philosophies>` * **Documentation:** - :ref:`About this documentation <internals-documentation>` + :doc:`About this documentation <internals/documentation>` * **Third-party distributions:** - :ref:`Overview <misc-distributions>` + :doc:`Overview <misc/distributions>` * **Django over time:** - :ref:`API stability <misc-api-stability>` | - :ref:`Release notes and upgrading instructions <releases-index>` | - :ref:`Deprecation Timeline <internals-deprecation>` + :doc:`API stability <misc/api-stability>` | + :doc:`Release notes and upgrading instructions <releases/index>` | + :doc:`Deprecation Timeline <internals/deprecation>` diff --git a/docs/internals/committers.txt b/docs/internals/committers.txt index d2eb80c710..b0bb18b955 100644 --- a/docs/internals/committers.txt +++ b/docs/internals/committers.txt @@ -1,5 +1,3 @@ -.. _internals-committers: - ================= Django committers ================= diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt index c555f205b1..399e458c2a 100644 --- a/docs/internals/contributing.txt +++ b/docs/internals/contributing.txt @@ -1,5 +1,3 @@ -.. _internals-contributing: - ====================== Contributing to Django ====================== @@ -42,7 +40,7 @@ amount of overhead involved in working with any bug tracking system, so your help in keeping our ticket tracker as useful as possible is appreciated. In particular: - * **Do** read the :ref:`FAQ <faq-index>` to see if your issue might be a well-known question. + * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might be a well-known question. * **Do** `search the tracker`_ to see if your issue has already been filed. @@ -145,7 +143,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -394,7 +396,7 @@ Various parts of Django, such as the admin site and validation error messages, are internationalized. This means they display different text depending on a user's language setting. For this, Django uses the same internationalization infrastructure available to Django applications described in the -:ref:`i18n documentation<topics-i18n>`. +:doc:`i18n documentation</topics/i18n/index>`. These translations are contributed by Django users worldwide. If you find an incorrect translation, or if you'd like to add a language that isn't yet @@ -405,7 +407,7 @@ translated, here's what to do: * Make sure you read the notes about :ref:`specialties-of-django-i18n`. * Create translations using the methods described in the - :ref:`localization documentation <topics-i18n-localization>`. For this + :doc:`localization documentation </topics/i18n/localization>`. For this you will use the ``django-admin.py makemessages`` tool. In this particular case it should be run from the top-level ``django`` directory of the Django source tree. @@ -531,8 +533,8 @@ Please follow these coding standards when writing code for inclusion in Django: * Use ``InitialCaps`` for class names (or for factory functions that return classes). - * Mark all strings for internationalization; see the :ref:`i18n - documentation <topics-i18n>` for details. + * Mark all strings for internationalization; see the :doc:`i18n + documentation </topics/i18n/index>` for details. * In docstrings, use "action words" such as:: @@ -694,8 +696,8 @@ General improvements, or other changes to the APIs that should be emphasized should use the ".. versionchanged:: X.Y" directive (with the same format as the ``versionadded`` mentioned above. -There's a full page of information about the :ref:`Django documentation -system <internals-documentation>` that you should read prior to working on the +There's a full page of information about the :doc:`Django documentation +system </internals/documentation>` that you should read prior to working on the documentation. Guidelines for ReST files @@ -825,7 +827,7 @@ The tests cover: We appreciate any and all contributions to the test suite! The Django tests all use the testing infrastructure that ships with Django for -testing applications. See :ref:`Testing Django applications <topics-testing>` +testing applications. See :doc:`Testing Django applications </topics/testing>` for an explanation of how to write new tests. Running the unit tests @@ -1013,8 +1015,8 @@ for feature branches: public, please add the branch to the `Django branches`_ wiki page. 2. Feature branches using SVN have a higher bar. If you want a branch in SVN - itself, you'll need a "mentor" among the :ref:`core committers - <internals-committers>`. This person is responsible for actually creating + itself, you'll need a "mentor" among the :doc:`core committers + </internals/committers>`. This person is responsible for actually creating the branch, monitoring your process (see below), and ultimately merging the branch into trunk. diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 8479a32bcf..b313871128 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -1,5 +1,3 @@ -.. _internals-deprecation: - =========================== Django Deprecation Timeline =========================== @@ -52,7 +50,7 @@ their deprecation, as per the :ref:`Django deprecation policy associated methods (``user.message_set.create()`` and ``user.get_and_delete_messages()``), which have been deprecated since the 1.2 release, will be removed. The - :ref:`messages framework <ref-contrib-messages>` should be used + :doc:`messages framework </ref/contrib/messages>` should be used instead. * Authentication backends need to support the ``obj`` parameter for @@ -100,6 +98,10 @@ their deprecation, as per the :ref:`Django deprecation policy * The ``no`` language code has been deprecated in favor of the ``nb`` language code. + * 1.5 + * The ``mod_python`` request handler has been deprecated since the 1.3 + release. The ``mod_wsgi`` handler should be used instead. + * 2.0 * ``django.views.defaults.shortcut()``. This function has been moved to ``django.contrib.contenttypes.views.shortcut()`` as part of the diff --git a/docs/internals/documentation.txt b/docs/internals/documentation.txt index 81480abf9a..63f248d3a9 100644 --- a/docs/internals/documentation.txt +++ b/docs/internals/documentation.txt @@ -1,5 +1,3 @@ -.. _internals-documentation: - How the Django documentation works ================================== @@ -15,6 +13,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.2 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 @@ -83,27 +86,55 @@ __ http://sphinx.pocoo.org/markup/desc.html An example ---------- -For a quick example of how it all fits together, check this out: +For a quick example of how it all fits together, consider this hypothetical +example: - * First, the ``ref/settings.txt`` document starts out like this:: + * First, the ``ref/settings.txt`` document could have an overall layout + like this: - .. _ref-settings: + .. code-block:: rst - Available settings - ================== + ======== + Settings + ======== ... - * Next, if you look at the ``topics/settings.txt`` document, you can see how - a link to ``ref/settings`` works:: + .. _available-settings: Available settings ================== - For a full list of available settings, see the :ref:`settings reference - <ref-settings>`. + ... + + .. _deprecated-settings: + + Deprecated settings + =================== + + ... + + * Next, the ``topics/settings.txt`` document could contain something like + this: + + .. code-block:: rst + + You can access a :ref:`listing of all available settings + <available-settings>`. For a list of deprecated settings see + :ref:`deprecated-settings`. + + You can find both in the :doc:`settings reference document </ref/settings>`. + + We use the Sphinx doc_ cross reference element when we want to link to + another document as a whole and the ref_ element when we want to link to + an arbitrary location in a document. + +.. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc +.. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref + + * Next, notice how the settings are annotated: - * Next, notice how the settings (right now just the top few) are annotated:: + .. code-block:: rst .. setting:: ADMIN_FOR diff --git a/docs/internals/index.txt b/docs/internals/index.txt index 4f9007705e..26c941a096 100644 --- a/docs/internals/index.txt +++ b/docs/internals/index.txt @@ -1,5 +1,3 @@ -.. _internals-index: - Django internals ================ diff --git a/docs/internals/release-process.txt b/docs/internals/release-process.txt index 20bc365844..2a56f0be92 100644 --- a/docs/internals/release-process.txt +++ b/docs/internals/release-process.txt @@ -1,5 +1,3 @@ -.. _internals-release-process: - ======================== Django's release process ======================== diff --git a/docs/internals/svn.txt b/docs/internals/svn.txt index 372fbd1202..c66e494e5f 100644 --- a/docs/internals/svn.txt +++ b/docs/internals/svn.txt @@ -1,5 +1,3 @@ -.. _internals-svn: - ================================= The Django source code repository ================================= @@ -87,8 +85,8 @@ the ``django`` module within your checkout. If you're going to be working on Django's code (say, to fix a bug or develop a new feature), you can probably stop reading here and move -over to :ref:`the documentation for contributing to Django -<internals-contributing>`, which covers things like the preferred +over to :doc:`the documentation for contributing to Django +</internals/contributing>`, which covers things like the preferred coding style and how to generate and submit a patch. @@ -129,20 +127,20 @@ part of Django itself, and so are no longer separately maintained: object-relational mapper. This has been part of Django since the 1.0 release, as the bundled application ``django.contrib.gis``. -* ``i18n``: Added :ref:`internationalization support <topics-i18n>` to +* ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to Django. This has been part of Django since the 0.90 release. * ``magic-removal``: A major refactoring of both the internals and public APIs of Django's object-relational mapper. This has been part of Django since the 0.95 release. -* ``multi-auth``: A refactoring of :ref:`Django's bundled - authentication framework <topics-auth>` which added support for +* ``multi-auth``: A refactoring of :doc:`Django's bundled + authentication framework </topics/auth>` which added support for :ref:`authentication backends <authentication-backends>`. This has been part of Django since the 0.95 release. -* ``new-admin``: A refactoring of :ref:`Django's bundled - administrative application <ref-contrib-admin>`. This became part of +* ``new-admin``: A refactoring of :doc:`Django's bundled + administrative application </ref/contrib/admin/index>`. This became part of Django as of the 0.91 release, but was superseded by another refactoring (see next listing) prior to the Django 1.0 release. diff --git a/docs/intro/index.txt b/docs/intro/index.txt index 2135bc7fe9..90ee627ba6 100644 --- a/docs/intro/index.txt +++ b/docs/intro/index.txt @@ -1,5 +1,3 @@ -.. _intro-index: - Getting started =============== diff --git a/docs/intro/install.txt b/docs/intro/install.txt index 901bde01c2..95728c75fc 100644 --- a/docs/intro/install.txt +++ b/docs/intro/install.txt @@ -1,10 +1,8 @@ -.. _intro-install: - Quick install guide =================== Before you can use Django, you'll need to get it installed. We have a -:ref:`complete installation guide <topics-install>` that covers all the +:doc:`complete installation guide </topics/install>` that covers all the possibilities; this guide will guide you to a simple, minimal installation that'll work while you walk through the introduction. @@ -12,9 +10,9 @@ Install Python -------------- Being a Python Web framework, Django requires Python. It works with any Python -version from 2.4 to 2.6 (due to backwards +version from 2.4 to 2.7 (due to backwards incompatibilities in Python 3.0, Django does not currently work with -Python 3.0; see :ref:`the Django FAQ <faq-install>` for more +Python 3.0; see :doc:`the Django FAQ </faq/install>` for more information on supported Python versions and the 3.0 transition), but we recommend installing Python 2.5 or later. If you do so, you won't need to set up a database just yet: Python 2.5 or later includes a lightweight database called SQLite_. .. _sqlite: http://sqlite.org/ @@ -25,17 +23,17 @@ probably already have it installed. .. admonition:: Django on Jython If you use Jython_ (a Python implementation for the Java platform), you'll - need to follow a few additional steps. See :ref:`howto-jython` for details. + need to follow a few additional steps. See :doc:`/howto/jython` for details. .. _jython: http://www.jython.org/ You can verify that Python's installed by typing ``python`` from your shell; you should see something like:: - Python 2.5.1 (r251:54863, Jan 17 2008, 19:35:17) + Python 2.5.1 (r251:54863, Jan 17 2008, 19:35:17) [GCC 4.0.1 (Apple Inc. build 5465)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> - + Set up a database ----------------- @@ -57,18 +55,18 @@ Install Django You've got three easy options to install Django: - * Install a version of Django :ref:`provided by your operating system - distribution <misc-distributions>`. This is the quickest option for those + * Install a version of Django :doc:`provided by your operating system + distribution </misc/distributions>`. This is the quickest option for those who have operating systems that distribute Django. * :ref:`Install an official release <installing-official-release>`. This is the best approach for users who want a stable version number and aren't concerned about running a slightly older version of Django. - + * :ref:`Install the latest development version <installing-development-version>`. This is best for users who want the latest-and-greatest features and aren't afraid of running brand-new code. - + .. warning:: If you do either of the first two steps, keep an eye out for parts of the @@ -79,7 +77,7 @@ You've got three easy options to install Django: That's it! ---------- -That's it -- you can now :ref:`move onto the tutorial <intro-tutorial01>`. +That's it -- you can now :doc:`move onto the tutorial </intro/tutorial01>`. diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 594c9fe582..0c47e59e14 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -1,5 +1,3 @@ -.. _intro-overview: - ================== Django at a glance ================== @@ -11,8 +9,8 @@ overview of how to write a database-driven Web app with Django. The goal of this document is to give you enough technical specifics to understand how Django works, but this isn't intended to be a tutorial or reference -- but we've got both! When you're ready to start a project, you can -:ref:`start with the tutorial <intro-tutorial01>` or :ref:`dive right into more -detailed documentation <topics-index>`. +:doc:`start with the tutorial </intro/tutorial01>` or :doc:`dive right into more +detailed documentation </topics/index>`. Design your model ================= @@ -21,7 +19,7 @@ Although you can use Django without a database, it comes with an object-relational mapper in which you describe your database layout in Python code. -The :ref:`data-model syntax <topics-db-models>` offers many rich ways of +The :doc:`data-model syntax </topics/db/models>` offers many rich ways of representing your models -- so far, it's been solving two years' worth of database-schema problems. Here's a quick example:: @@ -56,7 +54,7 @@ tables in your database for whichever tables don't already exist. Enjoy the free API ================== -With that, you've got a free, and rich, :ref:`Python API <topics-db-queries>` to +With that, you've got a free, and rich, :doc:`Python API </topics/db/queries>` to access your data. The API is created on the fly, no code generation necessary:: >>> from mysite.models import Reporter, Article @@ -131,7 +129,7 @@ A dynamic admin interface: it's not just scaffolding -- it's the whole house ============================================================================ Once your models are defined, Django can automatically create a professional, -production ready :ref:`administrative interface <ref-contrib-admin>` -- a Web +production ready :doc:`administrative interface </ref/contrib/admin/index>` -- a Web site that lets authenticated users add, change and delete objects. It's as easy as registering your model in the admin site:: @@ -168,8 +166,8 @@ A clean, elegant URL scheme is an important detail in a high-quality Web application. Django encourages beautiful URL design and doesn't put any cruft in URLs, like ``.php`` or ``.asp``. -To design URLs for an app, you create a Python module called a :ref:`URLconf -<topics-http-urls>`. A table of contents for your app, it contains a simple mapping +To design URLs for an app, you create a Python module called a :doc:`URLconf +</topics/http/urls>`. A table of contents for your app, it contains a simple mapping between URL patterns and Python callback functions. URLconfs also serve to decouple URLs from Python code. @@ -216,7 +214,7 @@ and renders the template with the retrieved data. Here's an example view for a_list = Article.objects.filter(pub_date__year=year) return render_to_response('news/year_archive.html', {'year': year, 'article_list': a_list}) -This example uses Django's :ref:`template system <topics-templates>`, which has +This example uses Django's :doc:`template system </topics/templates>`, which has several powerful features but strives to stay simple enough for non-programmers to use. @@ -307,17 +305,17 @@ This is just the surface This has been only a quick overview of Django's functionality. Some more useful features: - * A :ref:`caching framework <topics-cache>` that integrates with memcached + * A :doc:`caching framework </topics/cache>` that integrates with memcached or other backends. - * A :ref:`syndication framework <ref-contrib-syndication>` that makes + * A :doc:`syndication framework </ref/contrib/syndication>` that makes creating RSS and Atom feeds as easy as writing a small Python class. * More sexy automatically-generated admin features -- this overview barely scratched the surface. -The next obvious steps are for you to `download Django`_, read :ref:`the -tutorial <intro-tutorial01>` and join `the community`_. Thanks for your +The next obvious steps are for you to `download Django`_, read :doc:`the +tutorial </intro/tutorial01>` and join `the community`_. Thanks for your interest! .. _download Django: http://www.djangoproject.com/download/ diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index c38fa7d7f5..6045eb111e 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -1,5 +1,3 @@ -.. _intro-tutorial01: - ===================================== Writing your first Django app, part 1 ===================================== @@ -14,7 +12,7 @@ It'll consist of two parts: * A public site that lets people view polls and vote in them. * An admin site that lets you add, change and delete polls. -We'll assume you have :ref:`Django installed <intro-install>` already. You can +We'll assume you have :doc:`Django installed </intro/install>` already. You can tell Django is installed by running the Python interactive interpreter and typing ``import django``. If that command runs successfully, with no errors, Django is installed. @@ -47,8 +45,8 @@ create a ``mysite`` directory in your current directory. you try to run ``django-admin.py startproject``. This is because, on Unix-based systems like OS X, a file must be marked as "executable" before it can be run as a program. To do this, open Terminal.app and navigate (using - the ``cd`` command) to the directory where :ref:`django-admin.py - <ref-django-admin>` is installed, then run the command + the ``cd`` command) to the directory where :doc:`django-admin.py + </ref/django-admin>` is installed, then run the command ``chmod +x django-admin.py``. .. note:: @@ -58,11 +56,11 @@ create a ``mysite`` directory in your current directory. ``django`` (which will conflict with Django itself) or ``test`` (which conflicts with a built-in Python package). -:ref:`django-admin.py <ref-django-admin>` should be on your system path if you +:doc:`django-admin.py </ref/django-admin>` should be on your system path if you installed Django via ``python setup.py``. If it's not on your path, you can find it in ``site-packages/django/bin``, where ```site-packages``` is a directory -within your Python installation. Consider symlinking to :ref:`django-admin.py -<ref-django-admin>` from some place on your path, such as +within your Python installation. Consider symlinking to :doc:`django-admin.py +</ref/django-admin>` from some place on your path, such as :file:`/usr/local/bin`. .. admonition:: Where should this code live? @@ -93,14 +91,14 @@ These files are: * :file:`manage.py`: A command-line utility that lets you interact with this Django project in various ways. You can read all the details about - :file:`manage.py` in :ref:`ref-django-admin`. + :file:`manage.py` in :doc:`/ref/django-admin`. * :file:`settings.py`: Settings/configuration for this Django project. - :ref:`topics-settings` will tell you all about how settings work. + :doc:`/topics/settings` will tell you all about how settings work. * :file:`urls.py`: The URL declarations for this Django project; a "table of contents" of your Django-powered site. You can read more about URLs in - :ref:`topics-http-urls`. + :doc:`/topics/http/urls`. .. _more about packages: http://docs.python.org/tutorial/modules.html#packages @@ -473,7 +471,7 @@ added to your project since the last time you ran syncdb. :djadmin:`syncdb` can be called as often as you like, and it will only ever create the tables that don't exist. -Read the :ref:`django-admin.py documentation <ref-django-admin>` for full +Read the :doc:`django-admin.py documentation </ref/django-admin>` for full information on what the ``manage.py`` utility can do. Playing with the API @@ -508,10 +506,10 @@ things: set the ``DJANGO_SETTINGS_MODULE`` environment variable to ``mysite.settings``. - For more information on all of this, see the :ref:`django-admin.py - documentation <ref-django-admin>`. + For more information on all of this, see the :doc:`django-admin.py + documentation </ref/django-admin>`. -Once you're in the shell, explore the :ref:`database API <topics-db-queries>`:: +Once you're in the shell, explore the :doc:`database API </topics/db/queries>`:: >>> from mysite.polls.models import Poll, Choice # Import the model classes we just wrote. @@ -570,8 +568,8 @@ of this object. Let's fix that by editing the polls model (in the models and don't see any change in how they're represented, you're most likely using an old version of Django. (This version of the tutorial is written for the latest development version of Django.) If you're using a - Subversion checkout of Django's development version (see :ref:`the - installation docs <topics-install>` for more information), you shouldn't have + Subversion checkout of Django's development version (see :doc:`the + installation docs </topics/install>` for more information), you shouldn't have any problems. If you want to stick with an older version of Django, you'll want to switch @@ -693,9 +691,9 @@ Save these changes and start a new Python interactive shell by running >>> c = p.choice_set.filter(choice__startswith='Just hacking') >>> c.delete() -For more information on model relations, see :ref:`Accessing related objects -<ref-models-relations>`. For full details on the database API, see our -:ref:`Database API reference <topics-db-queries>`. +For more information on model relations, see :doc:`Accessing related objects +</ref/models/relations>`. For full details on the database API, see our +:doc:`Database API reference </topics/db/queries>`. -When you're comfortable with the API, read :ref:`part 2 of this tutorial -<intro-tutorial02>` to get Django's automatic admin working. +When you're comfortable with the API, read :doc:`part 2 of this tutorial +</intro/tutorial02>` to get Django's automatic admin working. diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index a7ab158faa..fcdb812c81 100644 --- a/docs/intro/tutorial02.txt +++ b/docs/intro/tutorial02.txt @@ -1,10 +1,8 @@ -.. _intro-tutorial02: - ===================================== Writing your first Django app, part 2 ===================================== -This tutorial begins where :ref:`Tutorial 1 <intro-tutorial01>` left off. We're +This tutorial begins where :doc:`Tutorial 1 </intro/tutorial01>` left off. We're continuing the Web-poll application and will focus on Django's automatically-generated admin site. @@ -426,7 +424,7 @@ Then, just edit the file and replace the generic Django text with your own site's name as you see fit. This template file contains lots of text like ``{% block branding %}`` -and ``{{ title }}. The ``{%`` and ``{{`` tags are part of Django's +and ``{{ title }}``. The ``{%`` and ``{{`` tags are part of Django's template language. When Django renders ``admin/base_site.html``, this template language will be evaluated to produce the final HTML page. Don't worry if you can't make any sense of the template right now -- @@ -463,5 +461,5 @@ object-specific admin pages in whatever way you think is best. Again, don't worry if you can't understand the template language -- we'll cover that in more detail in Tutorial 3. -When you're comfortable with the admin site, read :ref:`part 3 of this tutorial -<intro-tutorial03>` to start working on public poll views. +When you're comfortable with the admin site, read :doc:`part 3 of this tutorial +</intro/tutorial03>` to start working on public poll views. diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt index 0e09693778..1865b1bd5c 100644 --- a/docs/intro/tutorial03.txt +++ b/docs/intro/tutorial03.txt @@ -1,10 +1,8 @@ -.. _intro-tutorial03: - ===================================== Writing your first Django app, part 3 ===================================== -This tutorial begins where :ref:`Tutorial 2 <intro-tutorial02>` left off. We're +This tutorial begins where :doc:`Tutorial 2 </intro/tutorial02>` left off. We're continuing the Web-poll application and will focus on creating the public interface -- "views." @@ -68,8 +66,8 @@ arbitrary keyword arguments from the dictionary (an optional third item in the tuple). For more on :class:`~django.http.HttpRequest` objects, see the -:ref:`ref-request-response`. For more details on URLconfs, see the -:ref:`topics-http-urls`. +:doc:`/ref/request-response`. For more details on URLconfs, see the +:doc:`/topics/http/urls`. When you ran ``django-admin.py startproject mysite`` at the beginning of Tutorial 1, it created a default URLconf in ``mysite/urls.py``. It also @@ -205,7 +203,7 @@ you want, using whatever Python libraries you want. All Django wants is that :class:`~django.http.HttpResponse`. Or an exception. Because it's convenient, let's use Django's own database API, which we covered -in :ref:`Tutorial 1 <intro-tutorial01>`. Here's one stab at the ``index()`` +in :doc:`Tutorial 1 </intro/tutorial01>`. Here's one stab at the ``index()`` view, which displays the latest 5 poll questions in the system, separated by commas, according to publication date:: @@ -425,7 +423,7 @@ Method-calling happens in the ``{% for %}`` loop: ``poll.choice_set.all`` is interpreted as the Python code ``poll.choice_set.all()``, which returns an iterable of Choice objects and is suitable for use in the ``{% for %}`` tag. -See the :ref:`template guide <topics-templates>` for more about templates. +See the :doc:`template guide </topics/templates>` for more about templates. Simplifying the URLconfs ======================== @@ -514,5 +512,5 @@ under "/content/polls/", or any other URL root, and the app will still work. All the poll app cares about is its relative URLs, not its absolute URLs. -When you're comfortable with writing views, read :ref:`part 4 of this tutorial -<intro-tutorial04>` to learn about simple form processing and generic views. +When you're comfortable with writing views, read :doc:`part 4 of this tutorial +</intro/tutorial04>` to learn about simple form processing and generic views. diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt index ee3a3b2045..a7a9aaea33 100644 --- a/docs/intro/tutorial04.txt +++ b/docs/intro/tutorial04.txt @@ -1,10 +1,8 @@ -.. _intro-tutorial04: - ===================================== Writing your first Django app, part 4 ===================================== -This tutorial begins where :ref:`Tutorial 3 <intro-tutorial03>` left off. We're +This tutorial begins where :doc:`Tutorial 3 </intro/tutorial03>` left off. We're continuing the Web-poll application and will focus on simple form processing and cutting down our code. @@ -70,7 +68,7 @@ The details of how this works are explained in the documentation for :ref:`RequestContext <subclassing-context-requestcontext>`. Now, let's create a Django view that handles the submitted data and does -something with it. Remember, in :ref:`Tutorial 3 <intro-tutorial03>`, we +something with it. Remember, in :doc:`Tutorial 3 </intro/tutorial03>`, we created a URLconf for the polls application that includes this line:: (r'^(?P<poll_id>\d+)/vote/$', 'vote'), @@ -149,7 +147,7 @@ This code includes a few things we haven't covered yet in this tutorial: As mentioned in Tutorial 3, ``request`` is a :class:`~django.http.HttpRequest` object. For more on :class:`~django.http.HttpRequest` objects, see the -:ref:`request and response documentation <ref-request-response>`. +:doc:`request and response documentation </ref/request-response>`. After somebody votes in a poll, the ``vote()`` view redirects to the results page for the poll. Let's write that view:: @@ -158,8 +156,8 @@ page for the poll. Let's write that view:: p = get_object_or_404(Poll, pk=poll_id) return render_to_response('polls/results.html', {'poll': p}) -This is almost exactly the same as the ``detail()`` view from :ref:`Tutorial 3 -<intro-tutorial03>`. The only difference is the template name. We'll fix this +This is almost exactly the same as the ``detail()`` view from :doc:`Tutorial 3 +</intro/tutorial03>`. The only difference is the template name. We'll fix this redundancy later. Now, create a ``results.html`` template: @@ -183,7 +181,7 @@ without having chosen a choice, you should see the error message. Use generic views: Less code is better ====================================== -The ``detail()`` (from :ref:`Tutorial 3 <intro-tutorial03>`) and ``results()`` +The ``detail()`` (from :doc:`Tutorial 3 </intro/tutorial03>`) and ``results()`` views are stupidly simple -- and, as mentioned above, redundant. The ``index()`` view (also from Tutorial 3), which displays a list of polls, is similar. @@ -328,8 +326,8 @@ are) used multiple times -- but we can use the name we've given:: Run the server, and use your new polling app based on generic views. -For full details on generic views, see the :ref:`generic views documentation -<topics-http-generic-views>`. +For full details on generic views, see the :doc:`generic views documentation +</topics/http/generic-views>`. Coming soon =========== @@ -344,5 +342,5 @@ will cover: * Advanced admin features: Permissions * Advanced admin features: Custom JavaScript -In the meantime, you might want to check out some pointers on :ref:`where to go -from here <intro-whatsnext>` +In the meantime, you might want to check out some pointers on :doc:`where to go +from here </intro/whatsnext>` diff --git a/docs/intro/whatsnext.txt b/docs/intro/whatsnext.txt index 0949b2299e..fe385ffd9a 100644 --- a/docs/intro/whatsnext.txt +++ b/docs/intro/whatsnext.txt @@ -1,10 +1,8 @@ -.. _intro-whatsnext: - ================= What to read next ================= -So you've read all the :ref:`introductory material <intro-index>` and have +So you've read all the :doc:`introductory material </intro/index>` and have decided you'd like to keep using Django. We've only just scratched the surface with this intro (in fact, if you've read every single word you've still read less than 10% of the overall documentation). @@ -37,15 +35,15 @@ How the documentation is organized Django's main documentation is broken up into "chunks" designed to fill different needs: - * The :ref:`introductory material <intro-index>` is designed for people new + * The :doc:`introductory material </intro/index>` is designed for people new to Django -- or to web development in general. It doesn't cover anything in depth, but instead gives a high-level overview of how developing in Django "feels". - * The :ref:`topic guides <topics-index>`, on the other hand, dive deep into + * The :doc:`topic guides </topics/index>`, on the other hand, dive deep into individual parts of Django. There are complete guides to Django's - :ref:`model system <topics-db-index>`, :ref:`template engine - <topics-templates>`, :ref:`forms framework <topics-forms-index>`, and much + :doc:`model system </topics/db/index>`, :doc:`template engine + </topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much more. This is probably where you'll want to spend most of your time; if you work @@ -53,27 +51,27 @@ different needs: everything there is to know about Django. * Web development is often broad, not deep -- problems span many domains. - We've written a set of :ref:`how-to guides <howto-index>` that answer + We've written a set of :doc:`how-to guides </howto/index>` that answer common "How do I ...?" questions. Here you'll find information about - :ref:`generating PDFs with Django <howto-outputting-pdf>`, :ref:`writing - custom template tags <howto-custom-template-tags>`, and more. + :doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing + custom template tags </howto/custom-template-tags>`, and more. - Answers to really common questions can also be found in the :ref:`FAQ - <faq-index>`. + Answers to really common questions can also be found in the :doc:`FAQ + </faq/index>`. * The guides and how-to's don't cover every single class, function, and method available in Django -- that would be overwhelming when you're trying to learn. Instead, details about individual classes, functions, - methods, and modules are kept in the :ref:`reference <ref-index>`. This is + methods, and modules are kept in the :doc:`reference </ref/index>`. This is where you'll turn to find the details of a particular function or whathaveyou. * Finally, there's some "specialized" documentation not usually relevant to - most developers. This includes the :ref:`release notes <releases-index>`, - :ref:`documentation of obsolete features <obsolete-index>`, - :ref:`internals documentation <internals-index>` for those who want to add - code to Django itself, and a :ref:`few other things that simply don't fit - elsewhere <misc-index>`. + most developers. This includes the :doc:`release notes </releases/index>`, + :doc:`documentation of obsolete features </obsolete/index>`, + :doc:`internals documentation </internals/index>` for those who want to add + code to Django itself, and a :doc:`few other things that simply don't fit + elsewhere </misc/index>`. How documentation is updated @@ -187,11 +185,10 @@ You can get a local copy of the HTML documentation following a few easy steps: * The HTML documentation will be placed in ``docs/_build/html``. -.. warning:: +.. note:: - At the time of this writing, Django's using a version of Sphinx not - yet released, so you'll currently need to install Sphinx from the - source. We'll fix this shortly. + Generation of the Django documentation will work with Sphinx version 0.6 + or newer, but we recommend going straight to Sphinx 1.0.2 or newer. __ http://sphinx.pocoo.org/ __ http://www.gnu.org/software/make/ diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt index a648c873cc..70e5221592 100644 --- a/docs/misc/api-stability.txt +++ b/docs/misc/api-stability.txt @@ -1,10 +1,8 @@ -.. _misc-api-stability: - ============= API stability ============= -:ref:`The release of Django 1.0 <releases-1.0>` comes with a promise of API +:doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API stability and forwards-compatibility. In a nutshell, this means that code you develop against Django 1.0 will continue to work against 1.1 unchanged, and you should need to make only minor changes for any 1.X release. @@ -37,67 +35,67 @@ Stable APIs =========== In general, everything covered in the documentation -- with the exception of -anything in the :ref:`internals area <internals-index>` is considered stable as +anything in the :doc:`internals area </internals/index>` is considered stable as of 1.0. This includes these APIs: - - :ref:`Authorization <topics-auth>` + - :doc:`Authorization </topics/auth>` - - :ref:`Caching <topics-cache>`. + - :doc:`Caching </topics/cache>`. - - :ref:`Model definition, managers, querying and transactions - <topics-db-index>` + - :doc:`Model definition, managers, querying and transactions + </topics/db/index>` - - :ref:`Sending e-mail <topics-email>`. + - :doc:`Sending e-mail </topics/email>`. - - :ref:`File handling and storage <topics-files>` + - :doc:`File handling and storage </topics/files>` - - :ref:`Forms <topics-forms-index>` + - :doc:`Forms </topics/forms/index>` - - :ref:`HTTP request/response handling <topics-http-index>`, including file + - :doc:`HTTP request/response handling </topics/http/index>`, including file uploads, middleware, sessions, URL resolution, view, and shortcut APIs. - - :ref:`Generic views <topics-http-generic-views>`. + - :doc:`Generic views </topics/http/generic-views>`. - - :ref:`Internationalization <topics-i18n>`. + - :doc:`Internationalization </topics/i18n/index>`. - - :ref:`Pagination <topics-pagination>` + - :doc:`Pagination </topics/pagination>` - - :ref:`Serialization <topics-serialization>` + - :doc:`Serialization </topics/serialization>` - - :ref:`Signals <topics-signals>` + - :doc:`Signals </topics/signals>` - - :ref:`Templates <topics-templates>`, including the language, Python-level - :ref:`template APIs <ref-templates-index>`, and :ref:`custom template tags - and libraries <howto-custom-template-tags>`. We may add new template + - :doc:`Templates </topics/templates>`, including the language, Python-level + :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags + and libraries </howto/custom-template-tags>`. We may add new template tags in the future and the names may inadvertently clash with external template tags. Before adding any such tags, we'll ensure that Django raises an error if it tries to load tags with duplicate names. - - :ref:`Testing <topics-testing>` + - :doc:`Testing </topics/testing>` - - :ref:`django-admin utility <ref-django-admin>`. + - :doc:`django-admin utility </ref/django-admin>`. - - :ref:`Built-in middleware <ref-middleware>` + - :doc:`Built-in middleware </ref/middleware>` - - :ref:`Request/response objects <ref-request-response>`. + - :doc:`Request/response objects </ref/request-response>`. - - :ref:`Settings <ref-settings>`. Note, though that while the :ref:`list of - built-in settings <ref-settings>` can be considered complete we may -- and + - :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of + built-in settings </ref/settings>` can be considered complete we may -- and probably will -- add new settings in future versions. This is one of those places where "'stable' does not mean 'complete.'" - - :ref:`Built-in signals <ref-signals>`. Like settings, we'll probably add + - :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add new signals in the future, but the existing ones won't break. - - :ref:`Unicode handling <ref-unicode>`. + - :doc:`Unicode handling </ref/unicode>`. - - Everything covered by the :ref:`HOWTO guides <howto-index>`. + - Everything covered by the :doc:`HOWTO guides </howto/index>`. ``django.utils`` ---------------- Most of the modules in ``django.utils`` are designed for internal use. Only -the following parts of :ref:`django.utils <ref-utils>` can be considered stable: +the following parts of :doc:`django.utils </ref/utils>` can be considered stable: - ``django.utils.cache`` - ``django.utils.datastructures.SortedDict`` -- only this single class; the diff --git a/docs/misc/design-philosophies.txt b/docs/misc/design-philosophies.txt index 43bb8096c9..631097ae2b 100644 --- a/docs/misc/design-philosophies.txt +++ b/docs/misc/design-philosophies.txt @@ -1,5 +1,3 @@ -.. _misc-design-philosophies: - =================== Design philosophies =================== diff --git a/docs/misc/distributions.txt b/docs/misc/distributions.txt index 6a0845801d..d9281ad3da 100644 --- a/docs/misc/distributions.txt +++ b/docs/misc/distributions.txt @@ -1,5 +1,3 @@ -.. _misc-distributions: - =================================== Third-party distributions of Django =================================== diff --git a/docs/misc/index.txt b/docs/misc/index.txt index 534171b6ed..b42baeb9fd 100644 --- a/docs/misc/index.txt +++ b/docs/misc/index.txt @@ -1,5 +1,3 @@ -.. _misc-index: - Meta-documentation and miscellany ================================= diff --git a/docs/obsolete/admin-css.txt b/docs/obsolete/admin-css.txt index 4f8fb663e2..f4cca549b4 100644 --- a/docs/obsolete/admin-css.txt +++ b/docs/obsolete/admin-css.txt @@ -1,5 +1,3 @@ -.. _obsolete-admin-css: - ====================================== Customizing the Django admin interface ====================================== diff --git a/docs/obsolete/index.txt b/docs/obsolete/index.txt index 09e0826b88..ddc86237cc 100644 --- a/docs/obsolete/index.txt +++ b/docs/obsolete/index.txt @@ -1,5 +1,3 @@ -.. _obsolete-index: - Deprecated/obsolete documentation ================================= diff --git a/docs/ref/authbackends.txt b/docs/ref/authbackends.txt index 0e98c21b21..a50b414c78 100644 --- a/docs/ref/authbackends.txt +++ b/docs/ref/authbackends.txt @@ -1,5 +1,3 @@ -.. _ref-authentication-backends: - ======================= Authentication backends ======================= @@ -10,8 +8,8 @@ Authentication backends This document details the authentication backends that come with Django. For information on how to use them and how to write your own authentication backends, see the :ref:`Other authentication sources section -<authentication-backends>` of the :ref:`User authentication guide -<topics-auth>`. +<authentication-backends>` of the :doc:`User authentication guide +</topics/auth>`. Available authentication backends @@ -33,5 +31,5 @@ The following backends are available in :mod:`django.contrib.auth.backends`: Use this backend to take advantage of external-to-Django-handled authentication. It authenticates using usernames passed in :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`. See - the :ref:`Authenticating against REMOTE_USER <howto-auth-remote-user>` + the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>` documentation. diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt index 62f944d9b6..86a5355b28 100644 --- a/docs/ref/contrib/admin/actions.txt +++ b/docs/ref/contrib/admin/actions.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-admin-actions: - ============= Admin actions ============= @@ -208,7 +206,7 @@ objects. To provide an intermediary page, simply return an :class:`~django.http.HttpResponse` (or subclass) from your action. For example, you might write a simple export function that uses Django's -:ref:`serialization functions <topics-serialization>` to dump some selected +:doc:`serialization functions </topics/serialization>` to dump some selected objects as JSON:: from django.http import HttpResponse @@ -294,7 +292,7 @@ Disabling a site-wide action site-wide. If, however, you need to re-enable a globally-disabled action for one - particular model, simply list it explicitally in your ``ModelAdmin.actions`` + particular model, simply list it explicitly in your ``ModelAdmin.actions`` list:: # Globally disable delete selected diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 7fee903715..055057677c 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-admin: - ===================== The Django admin site ===================== @@ -7,8 +5,6 @@ The Django admin site .. module:: django.contrib.admin :synopsis: Django's admin site. -.. currentmodule:: django.contrib.admin - One of the most powerful parts of Django is the automatic admin interface. It reads metadata in your model to provide a powerful and production-ready interface that content producers can immediately use to start adding content to @@ -474,17 +470,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 +590,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 @@ -674,7 +674,7 @@ do that:: Note that the key in the dictionary is the actual field class, *not* a string. The value is another dictionary; these arguments will be passed to -:meth:`~django.forms.Field.__init__`. See :ref:`ref-forms-api` for details. +:meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for details. .. warning:: @@ -692,7 +692,7 @@ The value is another dictionary; these arguments will be passed to .. versionadded:: 1.1 A list of actions to make available on the change list page. See -:ref:`ref-contrib-admin-actions` for details. +:doc:`/ref/contrib/admin/actions` for details. .. attribute:: ModelAdmin.actions_on_top .. attribute:: ModelAdmin.actions_on_bottom @@ -743,8 +743,8 @@ templates used by the :class:`ModelAdmin` views: Path to a custom template, used by the :meth:`delete_selected` action method for displaying a confirmation page when deleting one - or more objects. See the :ref:`actions - documentation<ref-contrib-admin-actions>`. + or more objects. See the :doc:`actions + documentation</ref/contrib/admin/actions>`. .. attribute:: ModelAdmin.object_history_template @@ -801,7 +801,7 @@ described above in the :attr:`ModelAdmin.readonly_fields` section. The ``get_urls`` method on a ``ModelAdmin`` returns the URLs to be used for that ModelAdmin in the same way as a URLconf. Therefore you can extend them as -documented in :ref:`topics-http-urls`:: +documented in :doc:`/topics/http/urls`:: class MyModelAdmin(admin.ModelAdmin): def get_urls(self): @@ -829,7 +829,7 @@ problems: Since this is usually not what you want, Django provides a convenience wrapper to check permissions and mark the view as non-cacheable. This wrapper is -:meth:`AdminSite.admin_view` (i.e. ``self.admin_site.admin_view`` inside a +:meth:`AdminSite.admin_view` (i.e. ``self.admin_site.admin_view`` inside a ``ModelAdmin`` instance); use it like so:: class MyModelAdmin(admin.ModelAdmin): @@ -865,11 +865,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) @@ -950,7 +965,7 @@ on your ``ModelAdmin``:: js = ("my_code.js",) Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules -apply as :ref:`regular media definitions on forms <topics-forms-media>`. +apply as :doc:`regular media definitions on forms </topics/forms/media>`. Django admin Javascript makes use of the `jQuery`_ library. To avoid conflict with user scripts, Django's jQuery is namespaced as @@ -983,8 +998,8 @@ any field:: return self.cleaned_data["name"] It is important you use a ``ModelForm`` here otherwise things can break. See the -:ref:`forms <ref-forms-index>` documentation on :ref:`custom validation -<ref-forms-validation>` and, more specifically, the +:doc:`forms </ref/forms/index>` documentation on :doc:`custom validation +</ref/forms/validation>` and, more specifically, the :ref:`model form validation notes <overriding-modelform-clean-method>` for more information. @@ -993,6 +1008,8 @@ information. ``InlineModelAdmin`` objects ============================ +.. class:: InlineModelAdmin + The admin interface has the ability to edit models on the same page as a parent model. These are called inlines. Suppose you have these two models:: @@ -1027,90 +1044,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 + :doc:`formsets documentation </topics/forms/formsets>` for more information. -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. + .. versionadded:: 1.2 -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. + 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. .. _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 --------------------------------------------------------------------------- @@ -1189,7 +1204,7 @@ your admin page for managing the relation. In all other respects, the ``InlineModelAdmin`` is exactly the same as any other. You can customize the appearance using any of the normal -``InlineModelAdmin`` properties. +``ModelAdmin`` properties. Working with Many-to-Many Intermediary Models ---------------------------------------------- @@ -1281,7 +1296,7 @@ example app:: ``django.contrib.contenttypes.generic`` provides both a ``GenericTabularInline`` and ``GenericStackedInline`` and behave just like any other inline. See the -:ref:`contenttypes documentation <ref-contrib-contenttypes>` for more specific +:doc:`contenttypes documentation </ref/contrib/contenttypes>` for more specific information. Overriding Admin Templates diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index 03f5ff1281..619b38e5ac 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -1,6 +1,4 @@ -.. _ref-contrib-auth: - ``django.contrib.auth`` ======================= -See :ref:`topics-auth`. +See :doc:`/topics/auth`. diff --git a/docs/ref/contrib/comments/custom.txt b/docs/ref/contrib/comments/custom.txt index 9e32fc4fed..49299d4d33 100644 --- a/docs/ref/contrib/comments/custom.txt +++ b/docs/ref/contrib/comments/custom.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-custom: - ================================== Customizing the comments framework ================================== diff --git a/docs/ref/contrib/comments/example.txt b/docs/ref/contrib/comments/example.txt index d4ce623bb0..424bdb13f5 100644 --- a/docs/ref/contrib/comments/example.txt +++ b/docs/ref/contrib/comments/example.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-example: - .. highlightlang:: html+django =========================================== @@ -7,7 +5,7 @@ Example of using the in-built comments app =========================================== Follow the first three steps of the quick start guide in the -:ref:`documentation <ref-contrib-comments-index>`. +:doc:`documentation </ref/contrib/comments/index>`. Now suppose, you have an app (``blog``) with a model (``Post``) to which you want to attach comments. Let us also suppose that @@ -85,8 +83,8 @@ It looks for the ``form.html`` under the following directories Since we customize the form in the second method, we make use of another tag called :ttag:`comment_form_target`. This tag on rendering gives the URL -where the comment form is posted. Without any :ref:`customization -<ref-contrib-comments-custom>`, :ttag:`comment_form_target` evaluates to +where the comment form is posted. Without any :doc:`customization +</ref/contrib/comments/custom>`, :ttag:`comment_form_target` evaluates to ``/comments/post/``. We use this tag in the form's ``action`` attribute. The :ttag:`get_comment_form` tag renders a ``form`` for a model instance by @@ -136,7 +134,7 @@ found under the directory structure we saw for ``form.html``. Feeds ===== -Suppose you want to export a :ref:`feed <ref-contrib-syndication>` of the +Suppose you want to export a :doc:`feed </ref/contrib/syndication>` of the latest comments, you can use the in-built :class:`LatestCommentFeed`. Just enable it in your project's ``urls.py``: @@ -163,8 +161,8 @@ Moderation Now that we have the comments framework working, we might want to have some moderation setup to administer the comments. The comments framework comes -in-built with :ref:`generic comment moderation -<ref-contrib-comments-moderation>`. The comment moderation has the following +in-built with :doc:`generic comment moderation +</ref/contrib/comments/moderation>`. The comment moderation has the following features (all of which or only certain can be enabled): * Enable comments for a particular model instance. @@ -181,18 +179,18 @@ following way: from django.contrib.comments.moderation import CommentModerator, moderator from django.db import models - + class Post(models.Model): title = models.CharField(max_length = 255) content = models.TextField() posted_date = models.DateTimeField() - + class PostModerator(CommentModerator): email_notification = True auto_close_field = 'posted_date' # Close the comments after 7 days. close_after = 7 - + moderator.register(Post, PostModerator) The generic comment moderation also has the facility to remove comments. diff --git a/docs/ref/contrib/comments/forms.txt b/docs/ref/contrib/comments/forms.txt index 3eacb5db54..c21a27bb9e 100644 --- a/docs/ref/contrib/comments/forms.txt +++ b/docs/ref/contrib/comments/forms.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-forms: - ==================== Comment form classes ==================== @@ -9,7 +7,7 @@ Comment form classes The ``django.contrib.comments.forms`` module contains a handful of forms you'll use when writing custom views dealing with comments, or when writing -:ref:`custom comment apps <ref-contrib-comments-custom>`. +:doc:`custom comment apps </ref/contrib/comments/custom>`. .. class:: CommentForm @@ -23,7 +21,7 @@ you'll use when writing custom views dealing with comments, or when writing Abstract comment forms for custom comment apps ---------------------------------------------- -If you're building a :ref:`custom comment app <ref-contrib-comments-custom>`, +If you're building a :doc:`custom comment app </ref/contrib/comments/custom>`, you might want to replace *some* of the form logic but still rely on parts of the existing form. diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt index 9f1d3cd6e4..817871e976 100644 --- a/docs/ref/contrib/comments/index.txt +++ b/docs/ref/contrib/comments/index.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-index: - =========================== Django's comments framework =========================== @@ -16,7 +14,7 @@ it for comments on blog entries, photos, book chapters, or anything else. .. note:: If you used to use Django's older (undocumented) comments framework, you'll - need to upgrade. See the :ref:`upgrade guide <ref-contrib-comments-upgrade>` + need to upgrade. See the :doc:`upgrade guide </ref/contrib/comments/upgrade>` for instructions. Quick start guide @@ -42,7 +40,7 @@ To get started using the ``comments`` app, follow these steps: #. Use the `comment template tags`_ below to embed comments in your templates. -You might also want to examine :ref:`ref-contrib-comments-settings`. +You might also want to examine :doc:`/ref/contrib/comments/settings`. Comment template tags ===================== @@ -124,7 +122,7 @@ For example:: {% endfor %} This returns a list of :class:`~django.contrib.comments.models.Comment` objects; -see :ref:`the comment model documentation <ref-contrib-comments-models>` for +see :doc:`the comment model documentation </ref/contrib/comments/models>` for details. .. templatetag:: get_comment_permalink @@ -212,7 +210,7 @@ Rendering a custom comment form ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want more control over the look and feel of the comment form, you use use -:ttag:`get_comment_form` to get a :ref:`form object <topics-forms-index>` that +:ttag:`get_comment_form` to get a :doc:`form object </topics/forms/index>` that you can use in the template:: {% get_comment_form for [object] as [varname] %} @@ -279,8 +277,8 @@ should know about: it with a warning field; if you use the comment form with a custom template you should be sure to do the same. -The comments app also depends on the more general :ref:`Cross Site Request -Forgery protection < ref-contrib-csrf>` that comes with Django. As described in +The comments app also depends on the more general :doc:`Cross Site Request +Forgery protection </ref/contrib/csrf>` that comes with Django. As described in the documentation, it is best to use ``CsrfViewMiddleware``. However, if you are not using that, you will need to use the ``csrf_protect`` decorator on any views that include the comment form, in order for those views to be able to diff --git a/docs/ref/contrib/comments/models.txt b/docs/ref/contrib/comments/models.txt index af85d68f00..e773790d65 100644 --- a/docs/ref/contrib/comments/models.txt +++ b/docs/ref/contrib/comments/models.txt @@ -1,82 +1,80 @@ -.. _ref-contrib-comments-models: - =========================== The built-in comment models =========================== .. module:: django.contrib.comments.models :synopsis: The built-in comment models - + .. class:: Comment Django's built-in comment model. Has the following fields: - + .. attribute:: content_object - + A :class:`~django.contrib.contettypes.generic.GenericForeignKey` attribute pointing to the object the comment is attached to. You can use this to get at the related object (i.e. ``my_comment.content_object``). - + Since this field is a :class:`~django.contrib.contettypes.generic.GenericForeignKey`, it's actually syntactic sugar on top of two underlying attributes, described below. - + .. attribute:: content_type - + A :class:`~django.db.models.ForeignKey` to :class:`~django.contrib.contenttypes.models.ContentType`; this is the type of the object the comment is attached to. - + .. attribute:: object_pk - + A :class:`~django.db.models.TextField` containing the primary key of the object the comment is attached to. - + .. attribute:: site - + A :class:`~django.db.models.ForeignKey` to the :class:`~django.contrib.sites.models.Site` on which the comment was posted. - + .. attribute:: user - + A :class:`~django.db.models.ForeignKey` to the :class:`~django.contrib.auth.models.User` who posted the comment. May be blank if the comment was posted by an unauthenticated user. - + .. attribute:: user_name - + The name of the user who posted the comment. - + .. attribute:: user_email - - The email of the user who posteed the comment. - + + The email of the user who posted the comment. + .. attribute:: user_url - + The URL entered by the person who posted the comment. - + .. attribute:: comment - + The actual content of the comment itself. - + .. attribute:: submit_date - + The date the comment was submitted. - + .. attribute:: ip_address - + The IP address of the user posting the comment. - + .. attribute:: is_public - + ``False`` if the comment is in moderation (see - :ref:`ref-contrib-comments-moderation`); If ``True``, the comment will + :doc:`/ref/contrib/comments/moderation`); If ``True``, the comment will be displayed on the site. - + .. attribute:: is_removed - + ``True`` if the comment was removed. Used to keep track of removed comments instead of just deleting them. - + diff --git a/docs/ref/contrib/comments/moderation.txt b/docs/ref/contrib/comments/moderation.txt index 2c4072ba5b..198f78fa89 100644 --- a/docs/ref/contrib/comments/moderation.txt +++ b/docs/ref/contrib/comments/moderation.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-moderation: - ========================== Generic comment moderation ========================== diff --git a/docs/ref/contrib/comments/settings.txt b/docs/ref/contrib/comments/settings.txt index ff94d2dbcc..1f1aecafd4 100644 --- a/docs/ref/contrib/comments/settings.txt +++ b/docs/ref/contrib/comments/settings.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-settings: - ================ Comment settings ================ @@ -29,7 +27,7 @@ this will be rejected. Defaults to 3000. COMMENTS_APP ------------ -An app which provides :ref:`customization of the comments framework -<ref-contrib-comments-custom>`. Use the same dotted-string notation +An app which provides :doc:`customization of the comments framework +</ref/contrib/comments/custom>`. Use the same dotted-string notation as in :setting:`INSTALLED_APPS`. Your custom :setting:`COMMENTS_APP` must also be listed in :setting:`INSTALLED_APPS`. diff --git a/docs/ref/contrib/comments/signals.txt b/docs/ref/contrib/comments/signals.txt index cd406b56dd..7ae34a1900 100644 --- a/docs/ref/contrib/comments/signals.txt +++ b/docs/ref/contrib/comments/signals.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-signals: - ================================ Signals sent by the comments app ================================ @@ -7,9 +5,9 @@ Signals sent by the comments app .. module:: django.contrib.comments.signals :synopsis: Signals sent by the comment module. -The comment app sends a series of :ref:`signals <topics-signals>` to allow for -comment moderation and similar activities. See :ref:`the introduction to signals -<topics-signals>` for information about how to register for and receive these +The comment app sends a series of :doc:`signals </topics/signals>` to allow for +comment moderation and similar activities. See :doc:`the introduction to signals +</topics/signals>` for information about how to register for and receive these signals. comment_will_be_posted diff --git a/docs/ref/contrib/comments/upgrade.txt b/docs/ref/contrib/comments/upgrade.txt index dc9bff868c..3d6b5af668 100644 --- a/docs/ref/contrib/comments/upgrade.txt +++ b/docs/ref/contrib/comments/upgrade.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-upgrade: - =============================================== Upgrading from Django's previous comment system =============================================== @@ -11,8 +9,8 @@ The main changes from the old system are: * This new system is documented. - * It uses modern Django features like :ref:`forms <topics-forms-index>` and - :ref:`modelforms <topics-forms-modelforms>`. + * It uses modern Django features like :doc:`forms </topics/forms/index>` and + :doc:`modelforms </topics/forms/modelforms>`. * It has a single ``Comment`` model instead of separate ``FreeComment`` and ``Comment`` models. @@ -42,7 +40,7 @@ The data models for Django's comment system have changed, as have the table names. Before you transfer your existing data into the new comments system, make sure that you have installed the new comments system as explained in the -:ref:`quick start guide <ref-contrib-comments-index>`. +:doc:`quick start guide </ref/contrib/comments/index>`. This will ensure that the new tables have been properly created. To transfer your data into the new comments system, you'll need to directly diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 3085bf3ee9..b6956512ad 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-contenttypes: - ========================== The contenttypes framework ========================== @@ -114,7 +112,7 @@ Methods on ``ContentType`` instances Takes a set of valid :ref:`lookup arguments <field-lookups-intro>` for the model the :class:`~django.contrib.contenttypes.models.ContentType` - represents, and does :ref:`a get() lookup <get-kwargs>` on that model, + represents, and does :lookup:`a get() lookup <get>` on that model, returning the corresponding object. .. method:: models.ContentType.model_class() @@ -324,15 +322,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`.:: +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, content_type_field="content_type", object_id_field="object_pk") + comments = generic.GenericRelation(Comment, object_id_field="object_pk") -Note that if you delete an object that has a +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 @@ -342,7 +344,7 @@ it would be deleted at the same time. Generic relations and aggregation --------------------------------- -:ref:`Django's database aggregation API <topics-db-aggregation>` +:doc:`Django's database aggregation API </topics/db/aggregation>` doesn't work with a :class:`~django.contrib.contenttypes.generic.GenericRelation`. For example, you might be tempted to try something like:: @@ -361,14 +363,14 @@ Generic relations in forms and admin :class:`~django.contrib.contenttypes.generic.GenericInlineFormSet` and :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`. This enables the use of generic relations in forms and the admin. See the -:ref:`model formset <topics-forms-modelforms>` and -:ref:`admin <ref-contrib-admin>` documentation for more information. +:doc:`model formset </topics/forms/modelforms>` and +:doc:`admin </ref/contrib/admin/index>` documentation for more information. .. class:: generic.GenericInlineModelAdmin The :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin` class inherits all properties from an - :class:`~django.contrib.admin.options.InlineModelAdmin` class. However, + :class:`~django.contrib.admin.InlineModelAdmin` class. However, it adds a couple of its own for working with the generic relation: .. attribute:: generic.GenericInlineModelAdmin.ct_field diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt index d8a944b10a..c32dd73986 100644 --- a/docs/ref/contrib/csrf.txt +++ b/docs/ref/contrib/csrf.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-csrf: - ===================================== Cross Site Request Forgery protection ===================================== @@ -400,6 +398,13 @@ set a flag on requests which relaxes the middleware and the ``csrf_protect`` decorator so that they no longer rejects requests. In every other respect (e.g. sending cookies etc.), they behave the same. +If, for some reason, you *want* the test client to perform CSRF +checks, you can create an instance of the test client that enforces +CSRF checks:: + + >>> from django.test import Client + >>> csrf_client = Client(enforce_csrf_checks=True) + Limitations =========== diff --git a/docs/ref/contrib/databrowse.txt b/docs/ref/contrib/databrowse.txt index d3536d150c..33c8228520 100644 --- a/docs/ref/contrib/databrowse.txt +++ b/docs/ref/contrib/databrowse.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-databrowse: - ========== Databrowse ========== @@ -49,8 +47,8 @@ How to use Databrowse Note that you should register the model *classes*, not instances. It doesn't matter where you put this, as long as it gets executed at some - point. A good place for it is in your :ref:`URLconf file - <topics-http-urls>` (``urls.py``). + point. A good place for it is in your :doc:`URLconf file + </topics/http/urls>` (``urls.py``). 3. Change your URLconf to import the :mod:`~django.contrib.databrowse` module:: @@ -73,20 +71,20 @@ code. Simply add the following import to your URLconf:: from django.contrib.auth.decorators import login_required -Then modify the :ref:`URLconf <topics-http-urls>` so that the +Then modify the :doc:`URLconf </topics/http/urls>` so that the :func:`databrowse.site.root` view is decorated with :func:`django.contrib.auth.decorators.login_required`:: (r'^databrowse/(.*)', login_required(databrowse.site.root)), -If you haven't already added support for user logins to your :ref:`URLconf -<topics-http-urls>`, as described in the :ref:`user authentication docs -<ref-contrib-auth>`, then you will need to do so now with the following +If you haven't already added support for user logins to your :doc:`URLconf +</topics/http/urls>`, as described in the :doc:`user authentication docs +</ref/contrib/auth>`, then you will need to do so now with the following mapping:: (r'^accounts/login/$', 'django.contrib.auth.views.login'), The final step is to create the login form required by :func:`django.contrib.auth.views.login`. The -:ref:`user authentication docs <ref-contrib-auth>` provide full details and a +:doc:`user authentication docs </ref/contrib/auth>` provide full details and a sample template that can be used for this purpose. diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index 8c7f2781d0..ce6fdfcd1c 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-flatpages: - ================= The flatpages app ================= @@ -21,7 +19,7 @@ template. It can be associated with one, or multiple, sites. .. versionadded:: 1.0 -The content field may optionally be left blank if you prefer to put your +The content field may optionally be left blank if you prefer to put your content in a custom template. Here are some examples of flatpages on Django-powered sites: @@ -37,20 +35,20 @@ To install the flatpages app, follow these steps: 1. Install the :mod:`sites framework <django.contrib.sites>` by adding ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting, if it's not already in there. - + Also make sure you've correctly set :setting:`SITE_ID` to the ID of the site the settings file represents. This will usually be ``1`` (i.e. ``SITE_ID = 1``, but if you're using the sites framework to manage multiple sites, it could be the ID of a different site. - + 2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS` setting. - + 3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'`` to your :setting:`MIDDLEWARE_CLASSES` setting. - + 4. Run the command :djadmin:`manage.py syncdb <syncdb>`. - + How it works ============ @@ -69,7 +67,7 @@ If it finds a match, it follows this algorithm: * If the flatpage has a custom template, it loads that template. Otherwise, it loads the template :file:`flatpages/default.html`. - + * It passes that template a single context variable, :data:`flatpage`, which is the flatpage object. It uses :class:`~django.template.context.RequestContext` in rendering the @@ -92,11 +90,11 @@ Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can put :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at the end of the list, because it's a last resort. -For more on middleware, read the :ref:`middleware docs -<topics-http-middleware>`. +For more on middleware, read the :doc:`middleware docs +</topics/http/middleware>`. .. admonition:: Ensure that your 404 template works - + Note that the :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` only steps in once another view has successfully produced a 404 response. @@ -124,9 +122,9 @@ Via the Python API .. class:: models.FlatPage Flatpages are represented by a standard - :ref:`Django model <topics-db-models>`, + :doc:`Django model </topics/db/models>`, which lives in `django/contrib/flatpages/models.py`_. You can access - flatpage objects via the :ref:`Django database API <topics-db-queries>`. + flatpage objects via the :doc:`Django database API </topics/db/queries>`. .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py @@ -167,3 +165,64 @@ Since you're already entering raw HTML into the admin page for a flatpage, both ``flatpage.title`` and ``flatpage.content`` are marked as **not** requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the template. + +Getting a list of :class:`~django.contrib.flatpages.models.Flatpage` objects in your templates +============================================================================================== + +.. versionadded:: 1.3 + +The flatpages app provides a template tag that allows you to iterate +over all of the available flatpages on the :ref:`current site +<hooking-into-current-site-from-views>`. + +Like all custom template tags, you'll need to :ref:`load its custom +tag library <loading-custom-template-libraries>` before you can use +it. After loading the library, you can retrieve all current flatpages +via the :ttag:`get_flatpages` tag: + +.. code-block:: html+django + + {% load flatpages %} + {% get_flatpages as flatpages %} + <ul> + {% for page in flatpages %} + <li><a href="{{ page.url }}">{{ page.title }}</a></li> + {% endfor %} + </ul> + +.. templatetag:: get_flatpages + +Displaying ``registration_required`` flatpages +---------------------------------------------- + +By default, the :ttag:`get_flatpages` templatetag will only show +flatpages that are marked :attr:`registration_required`\=False. If you +want to display registration-protected flatpages, you need to specify +an authenticated user using a``for`` clause. + +For example: + +.. code-block:: html+django + + {% get_flatpages for someuser as about_pages %} + +If you provide an anonymous user, :ttag:`get_flatpages` will behave +the same as if you hadn't provided a user -- i.e., it will only show you +public flatpages. + +Limiting flatpages by base URL +------------------------------ + +An optional argument, ``starts_with``, can be applied to limit the +returned pages to those beginning with a particular base URL. This +argument may be passed as a string, or as a variable to be resolved +from the context. + +For example: + +.. code-block:: html+django + + {% get_flatpages '/about/' as about_pages %} + {% get_flatpages about_prefix as about_pages %} + {% get_flatpages '/about/' for someuser as about_pages %} + diff --git a/docs/ref/contrib/formtools/form-preview.txt b/docs/ref/contrib/formtools/form-preview.txt index ece69067ee..a2cbea704a 100644 --- a/docs/ref/contrib/formtools/form-preview.txt +++ b/docs/ref/contrib/formtools/form-preview.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-formtools-form-preview: - ============ Form preview ============ diff --git a/docs/ref/contrib/formtools/form-wizard.txt b/docs/ref/contrib/formtools/form-wizard.txt index 5ef862ce3d..ab7b4829c9 100644 --- a/docs/ref/contrib/formtools/form-wizard.txt +++ b/docs/ref/contrib/formtools/form-wizard.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-formtools-form-wizard: - =========== Form wizard =========== @@ -10,7 +8,7 @@ Form wizard .. versionadded:: 1.0 Django comes with an optional "form wizard" application that splits -:ref:`forms <topics-forms-index>` across multiple Web pages. It maintains +:doc:`forms </topics/forms/index>` across multiple Web pages. It maintains state in hashed HTML :samp:`<input type="hidden">` fields, and the data isn't processed server-side until the final form is submitted. @@ -65,8 +63,8 @@ Defining ``Form`` classes The first step in creating a form wizard is to create the :class:`~django.forms.Form` classes. These should be standard -:class:`django.forms.Form` classes, covered in the :ref:`forms documentation -<topics-forms-index>`. These classes can live anywhere in your codebase, but +:class:`django.forms.Form` classes, covered in the :doc:`forms documentation +</topics/forms/index>`. These classes can live anywhere in your codebase, but convention is to put them in a file called :file:`forms.py` in your application. @@ -189,8 +187,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/contrib/formtools/index.txt b/docs/ref/contrib/formtools/index.txt index 92010a25db..f36470654a 100644 --- a/docs/ref/contrib/formtools/index.txt +++ b/docs/ref/contrib/formtools/index.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-formtools-index: - django.contrib.formtools ======================== diff --git a/docs/ref/contrib/gis/admin.txt b/docs/ref/contrib/gis/admin.txt index df93c58504..011bb6b6bf 100644 --- a/docs/ref/contrib/gis/admin.txt +++ b/docs/ref/contrib/gis/admin.txt @@ -54,7 +54,7 @@ GeoDjango's admin site existing geometry fields in the admin. .. note:: - + This is different from adding the geometry field to :attr:`~django.contrib.admin.ModelAdmin.readonly_fields`, which will only display the WKT of the geometry. Setting diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt index 2cb7f69887..3dd161ce1d 100644 --- a/docs/ref/contrib/gis/commands.txt +++ b/docs/ref/contrib/gis/commands.txt @@ -78,6 +78,6 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`. all applicable fields. .. django-admin-option:: --srid - + The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts to automatically determine of the SRID of the data source. diff --git a/docs/ref/contrib/gis/create_template_postgis-1.4.sh b/docs/ref/contrib/gis/create_template_postgis-1.4.sh index 74a6ef98d2..57a1373f96 100755 --- a/docs/ref/contrib/gis/create_template_postgis-1.4.sh +++ b/docs/ref/contrib/gis/create_template_postgis-1.4.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.4 +POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib createdb -E UTF8 template_postgis # Create the template spatial database. createlang -d template_postgis plpgsql # Adding PLPGSQL language support. psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';" diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index 6797ce2de0..fbced8e6e1 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -14,7 +14,7 @@ Spatial Backends .. versionadded:: 1.2 -In Django 1.2, support for :ref:`multiple databases <topics-db-multi-db>` was +In Django 1.2, support for :doc:`multiple databases </topics/db/multi-db>` was introduced. In order to support multiple databases, GeoDjango has segregated its functionality into full-fledged spatial database backends: @@ -26,7 +26,7 @@ its functionality into full-fledged spatial database backends: Database Settings Backwards-Compatibility ----------------------------------------- -In :ref:`Django 1.2 <releases-1.2>`, the way +In :doc:`Django 1.2 </releases/1.2>`, the way to :ref:`specify databases <specifying-databases>` in your settings was changed. The old database settings format (e.g., the ``DATABASE_*`` settings) is backwards compatible with GeoDjango, and will automatically use the @@ -60,7 +60,7 @@ MySQL's spatial extensions only support bounding box operations [``Contains``, ``Crosses``, ``Disjoint``, ``Intersects``, ``Overlaps``, ``Touches``, ``Within``] according to the specification. Those that are implemented return - the same result as the corresponding MBR-based functions. + the same result as the corresponding MBR-based functions. In other words, while spatial lookups such as :lookup:`contains <gis-contains>` are available in GeoDjango when using MySQL, the results returned are really @@ -92,8 +92,8 @@ model):: >>> z.save() Moreover, if the ``GEOSGeometry`` is in a different coordinate system (has a -different SRID value) than that of the field, then it will be implicitly -transformed into the SRID of the model's field, using the spatial database's +different SRID value) than that of the field, then it will be implicitly +transformed into the SRID of the model's field, using the spatial database's transform procedure:: >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal' @@ -133,17 +133,17 @@ For example:: >>> qs = Zipcode.objects.filter(poly__contains=pnt) In this case, ``poly`` is the geographic field, :lookup:`contains <gis-contains>` -is the spatial lookup type, and ``pnt`` is the parameter (which may be a +is the spatial lookup type, and ``pnt`` is the parameter (which may be a :class:`~django.contrib.gis.geos.GEOSGeometry` object or a string of GeoJSON , WKT, or HEXEWKB). -A complete reference can be found in the :ref:`spatial lookup reference +A complete reference can be found in the :ref:`spatial lookup reference <spatial-lookups>`. .. note:: - GeoDjango constructs spatial SQL with the :class:`GeoQuerySet`, a - subclass of :class:`~django.db.models.QuerySet`. The + GeoDjango constructs spatial SQL with the :class:`GeoQuerySet`, a + subclass of :class:`~django.db.models.QuerySet`. The :class:`GeoManager` instance attached to your model is what enables use of :class:`GeoQuerySet`. @@ -156,8 +156,8 @@ Introduction ------------ Distance calculations with spatial data is tricky because, unfortunately, the Earth is not flat. Some distance queries with fields in a geographic -coordinate system may have to be expressed differently because of -limitations in PostGIS. Please see the :ref:`selecting-an-srid` section +coordinate system may have to be expressed differently because of +limitations in PostGIS. Please see the :ref:`selecting-an-srid` section in the :ref:`ref-gis-model-api` documentation for more details. .. _distance-lookups-intro: @@ -181,7 +181,7 @@ The following distance lookups are available: Distance lookups take a tuple parameter comprising: -#. A geometry to base calculations from; and +#. A geometry to base calculations from; and #. A number or :class:`~django.contrib.gis.measure.Distance` object containing the distance. If a :class:`~django.contrib.gis.measure.Distance` object is used, @@ -191,8 +191,8 @@ to be in the units of the field. .. note:: - For users of PostGIS 1.4 and below, the routine ``ST_Distance_Sphere`` - is used by default for calculating distances on geographic coordinate systems + For users of PostGIS 1.4 and below, the routine ``ST_Distance_Sphere`` + is used by default for calculating distances on geographic coordinate systems (e.g., WGS84) -- which may only be called with point geometries [#fndistsphere14]_. Thus, geographic distance lookups on traditional PostGIS geometry columns are only allowed on :class:`PointField` model fields using a point for the @@ -212,24 +212,24 @@ to be in the units of the field. You can tell GeoDjango to use a geography column by setting ``geography=True`` in your field definition. -For example, let's say we have a ``SouthTexasCity`` model (from the -`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities +For example, let's say we have a ``SouthTexasCity`` model (from the +`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities in southern Texas:: from django.contrib.gis.db import models - + class SouthTexasCity(models.Model): name = models.CharField(max_length=30) - # A projected coordinate system (only valid for South Texas!) + # A projected coordinate system (only valid for South Texas!) # is used, units are in meters. - point = models.PointField(srid=32140) + point = models.PointField(srid=32140) objects = models.GeoManager() Then distance queries may be performed as follows:: >>> from django.contrib.gis.geos import * >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance`` - >>> from geoapp import SouthTexasCity + >>> from geoapp import SouthTexasCity # Distances will be calculated from this point, which does not have to be projected. >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326) # If numeric parameter, units of field (meters in this case) are assumed. @@ -294,7 +294,7 @@ Lookup Type PostGIS Oracle MySQL [#]_ SpatiaLite ``GeoQuerySet`` Methods ----------------------- The following table provides a summary of what :class:`GeoQuerySet` methods -are available on each spatial backend. Please note that MySQL does not +are available on each spatial backend. Please note that MySQL does not support any of these methods, and is thus excluded from the table. ==================================== ======= ====== ========== @@ -330,7 +330,7 @@ Method PostGIS Oracle SpatiaLite :meth:`GeoQuerySet.translate` X X :meth:`GeoQuerySet.union` X X X :meth:`GeoQuerySet.unionagg` X X X -==================================== ======= ====== ========== +==================================== ======= ====== ========== .. rubric:: Footnotes .. [#fnwkt] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry). diff --git a/docs/ref/contrib/gis/deployment.txt b/docs/ref/contrib/gis/deployment.txt index 2cfd367fac..fa7fe69267 100644 --- a/docs/ref/contrib/gis/deployment.txt +++ b/docs/ref/contrib/gis/deployment.txt @@ -6,15 +6,15 @@ Deploying GeoDjango GeoDjango uses the GDAL geospatial library which is not thread safe at this time. Thus, it is *highly* recommended - to not use threading when deploying -- in other words, use a + to not use threading when deploying -- in other words, use a an appropriate configuration of Apache or the prefork method when using FastCGI through another web server. Apache ====== -In this section there are some example ``VirtualHost`` directives for +In this section there are some example ``VirtualHost`` directives for when deploying using either ``mod_python`` or ``mod_wsgi``. At this -time, we recommend ``mod_wsgi``, as it is now officially recommended +time, we recommend ``mod_wsgi``, as it is now officially recommended way to deploy Django applications with Apache. Moreover, if ``mod_python`` is used, then a prefork version of Apache must also be used. As long as ``mod_wsgi`` is configured correctly, it does not @@ -23,7 +23,7 @@ matter whether the version of Apache is prefork or worker. .. note:: The ``Alias`` and ``Directory`` configurations in the the examples - below use an example path to a system-wide installation folder of Django. + below use an example path to a system-wide installation folder of Django. Substitute in an appropriate location, if necessary, as it may be different than the path on your system. @@ -36,7 +36,7 @@ Example:: WSGIDaemonProcess geodjango user=geo group=geo processes=5 threads=1 WSGIProcessGroup geodjango WSGIScriptAlias / /home/geo/geodjango/world.wsgi - + Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/" <Directory "/usr/lib/python2.5/site-packages/django/contrib/admin/media/"> Order allow,deny @@ -44,25 +44,31 @@ Example:: Allow from all IndexOptions FancyIndexing </Directory> - + </VirtualHost> .. warning:: If the ``WSGIDaemonProcess`` attribute ``threads`` is not set to ``1``, then - Apache may crash when running your GeoDjango application. Increase the + Apache may crash when running your GeoDjango application. Increase the number of ``processes`` instead. For more information, please consult Django's -:ref:`mod_wsgi documentation <howto-deployment-modwsgi>`. +:doc:`mod_wsgi documentation </howto/deployment/modwsgi>`. ``mod_python`` -------------- +.. warning:: + Support for mod_python will be deprecated in a future release of Django. If + you are configuring a new deployment, you are strongly encouraged to + consider using :doc:`mod_wsgi </howto/deployment/modwsgi>` or any of the + other :doc:`supported backends </howto/deployment/index>`. + Example:: <VirtualHost *:80> - + <Location "/"> SetHandler mod_python PythonHandler django.core.handlers.modpython @@ -70,12 +76,12 @@ Example:: PythonDebug On PythonPath "['/var/www/apps'] + sys.path" </Location> - + Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/" <Location "/media"> SetHandler None </Location> - + </VirtualHost> .. warning:: @@ -84,7 +90,7 @@ Example:: else your GeoDjango application may crash Apache. For more information, please consult Django's -:ref:`mod_python documentation <howto-deployment-modpython>`. +:doc:`mod_python documentation </howto/deployment/modpython>`. Lighttpd ======== diff --git a/docs/ref/contrib/gis/feeds.txt b/docs/ref/contrib/gis/feeds.txt index bb9c12ae5d..7c3a2d011c 100644 --- a/docs/ref/contrib/gis/feeds.txt +++ b/docs/ref/contrib/gis/feeds.txt @@ -1,5 +1,3 @@ -.. _ref-gis-feeds: - ================ Geographic Feeds ================ @@ -8,10 +6,10 @@ Geographic Feeds :synopsis: GeoDjango's framework for generating spatial feeds. GeoDjango has its own :class:`Feed` subclass that may embed location information -in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or +in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or `W3C Geo`_ standards. Because GeoDjango's syndication API is a superset of -Django's, please consult `Django's syndication documentation <ref-contrib-syndication>` -for details on general usage. +Django's, please consult :doc:`Django's syndication documentation +</ref/contrib/syndication>` for details on general usage. .. _W3C Geo: http://www.w3.org/2003/01/geo/ @@ -28,7 +26,7 @@ API Reference .. class:: Feed - In addition to methods provided by + In addition to methods provided by the :class:`django.contrib.syndication.feeds.Feed` base class, GeoDjango's ``Feed`` class provides the following overrides. Note that these overrides may be done in multiple ways:: diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt index c413ff4157..69f0c02e86 100644 --- a/docs/ref/contrib/gis/geoquerysets.txt +++ b/docs/ref/contrib/gis/geoquerysets.txt @@ -14,12 +14,12 @@ GeoQuerySet API Reference Spatial Lookups =============== -Just like when using the the :ref:`queryset-api`, interaction +Just like when using the the :ref:`queryset-api`, interaction with ``GeoQuerySet`` by :ref:`chaining filters <chaining-filters>`. Instead of the regular Django :ref:`field-lookups`, the spatial lookups in this section are available for :class:`GeometryField`. -For an introduction, see the :ref:`spatial lookups introduction +For an introduction, see the :ref:`spatial lookups introduction <spatial-lookups-intro>`. For an overview of what lookups are compatible with a particular spatial backend, refer to the :ref:`spatial lookup compatibility table <spatial-lookup-compatibility>`. @@ -31,7 +31,7 @@ bbcontains *Availability*: PostGIS, MySQL, SpatiaLite -Tests if the geometry field's bounding box completely contains the lookup +Tests if the geometry field's bounding box completely contains the lookup geometry's bounding box. Example:: @@ -53,7 +53,7 @@ bboverlaps *Availability*: PostGIS, MySQL, SpatiaLite -Tests if the geometry field's bounding box overlaps the lookup geometry's +Tests if the geometry field's bounding box overlaps the lookup geometry's bounding box. Example:: @@ -277,9 +277,9 @@ the values given in the given pattern. This lookup requires a tuple parameter, PostGIS & SpatiaLite ~~~~~~~~~~~~~~~~~~~~ -On these spatial backends the intersection pattern is a string comprising -nine characters, which define intersections between the interior, boundary, -and exterior of the geometry field and the lookup geometry. +On these spatial backends the intersection pattern is a string comprising +nine characters, which define intersections between the interior, boundary, +and exterior of the geometry field and the lookup geometry. The intersection pattern matrix may only use the following characters: ``1``, ``2``, ``T``, ``F``, or ``*``. This lookup type allows users to "fine tune" a specific geometric relationship consistent with the DE-9IM model. [#fnde9im]_ @@ -302,7 +302,7 @@ Oracle ~~~~~~ Here the relation pattern is compreised at least one of the nine relation -strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``, +strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``, ``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ON``, and ``ANYINTERACT``. Multiple strings may be combined with the logical Boolean operator OR, for example, ``'inside+touch'``. [#fnsdorelate]_ The relation @@ -312,7 +312,7 @@ Example:: Zipcode.objects.filter(poly__relate(geom, 'anyinteract')) -Oracle SQL equivalent:: +Oracle SQL equivalent:: SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract') @@ -403,7 +403,7 @@ overlaps_left *Availability*: PostGIS -Tests if the geometry field's bounding box overlaps or is to the left of the lookup +Tests if the geometry field's bounding box overlaps or is to the left of the lookup geometry's bounding box. Example:: @@ -422,7 +422,7 @@ overlaps_right *Availability*: PostGIS -Tests if the geometry field's bounding box overlaps or is to the right of the lookup +Tests if the geometry field's bounding box overlaps or is to the right of the lookup geometry's bounding box. Example:: @@ -440,7 +440,7 @@ overlaps_above *Availability*: PostGIS -Tests if the geometry field's bounding box overlaps or is above the lookup +Tests if the geometry field's bounding box overlaps or is above the lookup geometry's bounding box. Example:: @@ -458,7 +458,7 @@ overlaps_below *Availability*: PostGIS -Tests if the geometry field's bounding box overlaps or is below the lookup +Tests if the geometry field's bounding box overlaps or is below the lookup geometry's bounding box. Example:: @@ -476,7 +476,7 @@ strictly_above *Availability*: PostGIS -Tests if the geometry field's bounding box is strictly above the lookup +Tests if the geometry field's bounding box is strictly above the lookup geometry's bounding box. Example:: @@ -494,7 +494,7 @@ strictly_below *Availability*: PostGIS -Tests if the geometry field's bounding box is strictly above the lookup +Tests if the geometry field's bounding box is strictly above the lookup geometry's bounding box. Example:: @@ -662,7 +662,7 @@ Keyword Argument Description ===================== ===================================================== ``field_name`` By default, ``GeoQuerySet`` methods use the first geographic field encountered in the model. This - keyword should be used to specify another + keyword should be used to specify another geographic field (e.g., ``field_name='point2'``) when there are multiple geographic fields in a model. @@ -670,7 +670,7 @@ Keyword Argument Description used on geometry fields in models that are related via a ``ForeignKey`` relation (e.g., ``field_name='related__point'``). - + ``model_att`` By default, ``GeoQuerySet`` methods typically attach their output in an attribute with the same name as the ``GeoQuerySet`` method. Setting this keyword @@ -679,12 +679,12 @@ Keyword Argument Description ``qs = Zipcode.objects.centroid(model_att='c')`` will attach the centroid of the ``Zipcode`` geometry field in a ``c`` attribute on every model rather than in a - ``centroid`` attribute. + ``centroid`` attribute. - This keyword is required if - a method name clashes with an existing - ``GeoQuerySet`` method -- if you wanted to use the - ``area()`` method on model with a ``PolygonField`` + This keyword is required if + a method name clashes with an existing + ``GeoQuerySet`` method -- if you wanted to use the + ``area()`` method on model with a ``PolygonField`` named ``area``, for example. ===================== ===================================================== @@ -705,12 +705,12 @@ each element of this GeoQuerySet. .. method:: GeoQuerySet.distance(geom, **kwargs) -This method takes a geometry as a parameter, and attaches a ``distance`` -attribute to every model in the returned queryset that contains the +This method takes a geometry as a parameter, and attaches a ``distance`` +attribute to every model in the returned queryset that contains the distance (as a :class:`~django.contrib.gis.measure.Distance` object) to the given geometry. -In the following example (taken from the `GeoDjango distance tests`__), -the distance from the `Tasmanian`__ city of Hobart to every other +In the following example (taken from the `GeoDjango distance tests`__), +the distance from the `Tasmanian`__ city of Hobart to every other :class:`PointField` in the ``AustraliaCity`` queryset is calculated:: >>> pnt = AustraliaCity.objects.get(name='Hobart').point @@ -732,7 +732,7 @@ the distance from the `Tasmanian`__ city of Hobart to every other Because the ``distance`` attribute is a :class:`~django.contrib.gis.measure.Distance` object, you can easily express the value in the units of your choice. For example, ``city.distance.mi`` is - the distance value in miles and ``city.distance.km`` is the distance value + the distance value in miles and ``city.distance.km`` is the distance value in kilometers. See the :ref:`ref-measure` for usage details and the list of :ref:`supported_units`. @@ -867,9 +867,9 @@ then 4326 (WGS84) is used by default. geometry is placed on the models. .. note:: - - What spatial reference system an integer SRID corresponds to may depend on - the spatial database used. In other words, the SRID numbers used for Oracle + + What spatial reference system an integer SRID corresponds to may depend on + the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS. Example:: @@ -903,7 +903,7 @@ to each element of the ``GeoQuerySet`` that is the result of the operation. .. method:: GeoQuerySet.difference(geom) Returns the spatial difference of the geographic field with the given -geometry in a ``difference`` attribute on each element of the +geometry in a ``difference`` attribute on each element of the ``GeoQuerySet``. @@ -913,7 +913,7 @@ geometry in a ``difference`` attribute on each element of the .. method:: GeoQuerySet.intersection(geom) Returns the spatial intersection of the geographic field with the -given geometry in an ``intersection`` attribute on each element of the +given geometry in an ``intersection`` attribute on each element of the ``GeoQuerySet``. ``sym_difference`` @@ -937,7 +937,7 @@ geometry in an ``union`` attribute on each element of the Geometry Output --------------- -The following ``GeoQuerySet`` methods will return an attribute that has the value +The following ``GeoQuerySet`` methods will return an attribute that has the value of the geometry field in each model converted to the requested output format. ``geohash`` @@ -967,8 +967,8 @@ Attaches a ``geojson`` attribute to every model in the queryset that contains th ===================== ===================================================== Keyword Argument Description ===================== ===================================================== -``precision`` It may be used to specify the number of significant - digits for the coordinates in the GeoJSON +``precision`` It may be used to specify the number of significant + digits for the coordinates in the GeoJSON representation -- the default value is 8. ``crs`` Set this to ``True`` if you want the coordinate @@ -988,8 +988,8 @@ __ http://geojson.org/ *Availability*: PostGIS, Oracle -Attaches a ``gml`` attribute to every model in the queryset that contains the -`Geographic Markup Language (GML)`__ representation of the geometry. +Attaches a ``gml`` attribute to every model in the queryset that contains the +`Geographic Markup Language (GML)`__ representation of the geometry. Example:: @@ -1000,9 +1000,9 @@ Example:: ===================== ===================================================== Keyword Argument Description ===================== ===================================================== -``precision`` This keyword is for PostGIS only. It may be used - to specify the number of significant digits for the - coordinates in the GML representation -- the default +``precision`` This keyword is for PostGIS only. It may be used + to specify the number of significant digits for the + coordinates in the GML representation -- the default value is 8. ``version`` This keyword is for PostGIS only. It may be used to @@ -1019,9 +1019,9 @@ __ http://en.wikipedia.org/wiki/Geography_Markup_Language *Availability*: PostGIS -Attaches a ``kml`` attribute to every model in the queryset that contains the -`Keyhole Markup Language (KML)`__ representation of the geometry fields. It -should be noted that the contents of the KML are transformed to WGS84 if +Attaches a ``kml`` attribute to every model in the queryset that contains the +`Keyhole Markup Language (KML)`__ representation of the geometry fields. It +should be noted that the contents of the KML are transformed to WGS84 if necessary. Example:: @@ -1033,8 +1033,8 @@ Example:: ===================== ===================================================== Keyword Argument Description ===================== ===================================================== -``precision`` This keyword may be used to specify the number of - significant digits for the coordinates in the KML +``precision`` This keyword may be used to specify the number of + significant digits for the coordinates in the KML representation -- the default value is 8. ===================== ===================================================== @@ -1054,11 +1054,11 @@ the `Scalable Vector Graphics (SVG)`__ path data of the geometry fields. Keyword Argument Description ===================== ===================================================== ``relative`` If set to ``True``, the path data will be implemented - in terms of relative moves. Defaults to ``False``, + in terms of relative moves. Defaults to ``False``, meaning that absolute moves are used instead. -``precision`` This keyword may be used to specify the number of - significant digits for the coordinates in the SVG +``precision`` This keyword may be used to specify the number of + significant digits for the coordinates in the SVG representation -- the default value is 8. ===================== ===================================================== @@ -1129,7 +1129,7 @@ dissolving boundaries. *Availability*: PostGIS, Oracle -Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the +Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the lower left coordinate and the upper right coordinate. Example:: @@ -1163,7 +1163,7 @@ Example:: *Availability*: PostGIS -Returns a ``LineString`` constructed from the point field geometries in the +Returns a ``LineString`` constructed from the point field geometries in the ``GeoQuerySet``. Currently, ordering the queryset has no effect. Example:: @@ -1184,25 +1184,25 @@ use of ``unionagg`` is processor intensive and may take a significant amount of time on large querysets. .. note:: - + If the computation time for using this method is too expensive, consider using :meth:`GeoQuerySet.collect` instead. Example:: - + >>> u = Zipcode.objects.unionagg() # This may take a long time. >>> u = Zipcode.objects.filter(poly__within=bbox).unionagg() # A more sensible approach. ===================== ===================================================== Keyword Argument Description ===================== ===================================================== -``tolerance`` This keyword is for Oracle only. It is for the +``tolerance`` This keyword is for Oracle only. It is for the tolerance value used by the ``SDOAGGRTYPE`` - procedure; the `Oracle documentation`__ has more + procedure; the `Oracle documentation`__ has more details. ===================== ===================================================== -__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150 +__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150 Aggregate Functions ------------------- diff --git a/docs/ref/contrib/gis/install.txt b/docs/ref/contrib/gis/install.txt index 00d4e62e9f..ae36e167ae 100644 --- a/docs/ref/contrib/gis/install.txt +++ b/docs/ref/contrib/gis/install.txt @@ -13,7 +13,7 @@ In general, GeoDjango installation requires: 3. :ref:`geospatial_libs` Details for each of the requirements and installation instructions -are provided in the sections below. In addition, platform-specific +are provided in the sections below. In addition, platform-specific instructions are available for: * :ref:`macosx` @@ -23,10 +23,10 @@ instructions are available for: .. admonition:: Use the Source Because GeoDjango takes advantage of the latest in the open source geospatial - software technology, recent versions of the libraries are necessary. + software technology, recent versions of the libraries are necessary. If binary packages aren't available for your platform, :ref:`installation from source <build_from_source>` - may be required. When compiling the libraries from source, please follow the + may be required. When compiling the libraries from source, please follow the directions closely, especially if you're a beginner. Requirements @@ -37,8 +37,8 @@ Requirements Python 2.4+ ----------- Because of heavy use of the decorator syntax, Python 2.4 is minimum -version supported by GeoDjango. Python 2.5+ is recommended because the -`ctypes`__ module comes included; otherwise, 2.4 users will need to +version supported by GeoDjango. Python 2.5+ is recommended because the +`ctypes`__ module comes included; otherwise, 2.4 users will need to `download and install ctypes`__. __ http://docs.python.org/lib/module-ctypes.html @@ -50,18 +50,18 @@ Django ------ Because GeoDjango is included with Django, please refer to Django's -:ref:`installation instructions <intro-install>` for details on how to install. +:doc:`installation instructions </intro/install>` for details on how to install. .. _spatial_database: Spatial Database ---------------- -PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are +PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are the spatial databases currently supported. .. note:: - PostGIS is recommended, because it is the most mature and feature-rich + PostGIS is recommended, because it is the most mature and feature-rich open source spatial database. The geospatial libraries required for a GeoDjango installation depends @@ -81,7 +81,7 @@ SQLite GEOS, GDAL, PROJ.4, SpatiaLite 3.6.+ Requires Geospatial Libraries -------------------- -GeoDjango uses and/or provides interfaces for the the following open source +GeoDjango uses and/or provides interfaces for the the following open source geospatial libraries: ======================== ==================================== ================================ ========================== @@ -117,7 +117,7 @@ Building from Source ==================== When installing from source on UNIX and GNU/Linux systems, please follow -the installation instructions carefully, and install the libraries in the +the installation instructions carefully, and install the libraries in the given order. If using MySQL or Oracle as the spatial database, only GEOS is required. @@ -147,13 +147,13 @@ internal geometry representation used by GeoDjango (it's behind the "lazy" geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``) directly from Python using ctypes. -First, download GEOS 3.2 from the refractions website and untar the source +First, download GEOS 3.2 from the refractions website and untar the source archive:: $ wget http://download.osgeo.org/geos/geos-3.2.2.tar.bz2 $ tar xjf geos-3.2.2.tar.bz2 -Next, change into the directory where GEOS was unpacked, run the configure +Next, change into the directory where GEOS was unpacked, run the configure script, compile, and install:: $ cd geos-3.2.2 @@ -172,7 +172,7 @@ When GeoDjango can't find GEOS, this error is raised:: ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings. -The most common solution is to properly configure your :ref:`libsettings` *or* set +The most common solution is to properly configure your :ref:`libsettings` *or* set :ref:`geoslibrarypath` in your settings. If using a binary package of GEOS (e.g., on Ubuntu 8.10), you may need to :ref:`binutils`. @@ -191,7 +191,7 @@ C library. For example:: .. note:: - The setting must be the *full* path to the **C** shared library; in + The setting must be the *full* path to the **C** shared library; in other words you want to use ``libgeos_c.so``, not ``libgeos.so``. .. _proj4: @@ -199,7 +199,7 @@ C library. For example:: PROJ.4 ------ -`PROJ.4`_ is a library for converting geospatial data to different coordinate +`PROJ.4`_ is a library for converting geospatial data to different coordinate reference systems. First, download the PROJ.4 source code and datum shifting files [#]_:: @@ -228,12 +228,12 @@ PostGIS ------- `PostGIS`__ adds geographic object support to PostgreSQL, turning it -into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be +into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building PostGIS. .. note:: - The `psycopg2`_ module is required for use as the database adaptor + The `psycopg2`_ module is required for use as the database adaptor when using GeoDjango with PostGIS. .. _psycopg2: http://initd.org/projects/psycopg2 @@ -256,7 +256,7 @@ Finally, make and install:: .. note:: - GeoDjango does not automatically create a spatial database. Please + GeoDjango does not automatically create a spatial database. Please consult the section on :ref:`spatialdb_template` for more information. __ http://postgis.refractions.net/ @@ -267,7 +267,7 @@ GDAL ---- `GDAL`__ is an excellent open source geospatial library that has support for -reading most vector and raster spatial data formats. Currently, GeoDjango only +reading most vector and raster spatial data formats. Currently, GeoDjango only supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL. @@ -287,11 +287,11 @@ Configure, make and install:: .. note:: Because GeoDjango has it's own Python interface, the preceding instructions - do not build GDAL's own Python bindings. The bindings may be built by + do not build GDAL's own Python bindings. The bindings may be built by adding the ``--with-python`` flag when running ``configure``. See - `GDAL/OGR In Python`__ for more information on GDAL's bindings. + `GDAL/OGR In Python`__ for more information on GDAL's bindings. -If you have any problems, please see the troubleshooting section below for +If you have any problems, please see the troubleshooting section below for suggestions and solutions. __ http://trac.osgeo.org/gdal/ @@ -312,7 +312,7 @@ will be false:: >>> gdal.HAS_GDAL False -The solution is to properly configure your :ref:`libsettings` *or* set +The solution is to properly configure your :ref:`libsettings` *or* set :ref:`gdallibrarypath` in your settings. .. _gdallibrarypath: @@ -332,22 +332,22 @@ the GDAL library. For example:: Can't find GDAL data files (``GDAL_DATA``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When installed from source, GDAL versions 1.5.1 and below have an autoconf bug -that places data in the wrong location. [#]_ This can lead to error messages +When installed from source, GDAL versions 1.5.1 and below have an autoconf bug +that places data in the wrong location. [#]_ This can lead to error messages like this:: ERROR 4: Unable to open EPSG support file gcs.csv. ... OGRException: OGR failure. -The solution is to set the ``GDAL_DATA`` environment variable to the location of the -GDAL data files before invoking Python (typically ``/usr/local/share``; use +The solution is to set the ``GDAL_DATA`` environment variable to the location of the +GDAL data files before invoking Python (typically ``/usr/local/share``; use ``gdal-config --datadir`` to find out). For example:: $ export GDAL_DATA=`gdal-config --datadir` $ python manage.py shell -If using Apache, you may need to add this environment variable to your configuration +If using Apache, you may need to add this environment variable to your configuration file:: SetEnv GDAL_DATA /usr/local/share @@ -363,13 +363,13 @@ SpatiaLite Mac OS X users should follow the instructions in the :ref:`kyngchaos` section, as it is much easier than building from source. -`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured +`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured spatial database. Because SpatiaLite has special requirements, it typically -requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from +requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from source. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building SpatiaLite. -After installation is complete, don't forget to read the post-installation +After installation is complete, don't forget to read the post-installation docs on :ref:`create_spatialite_db`. __ http://www.gaia-gis.it/spatialite/index.html @@ -380,12 +380,12 @@ SQLite ^^^^^^ Typically, SQLite packages are not compiled to include the `R*Tree module`__ -- -thus it must be compiled from source. First download the latest amalgamation +thus it must be compiled from source. First download the latest amalgamation source archive from the `SQLite download page`__, and extract:: - $ wget http://www.sqlite.org/sqlite-amalgamation-3.6.22.tar.gz - $ tar xzf sqlite-amalgamation-3.6.22.tar.gz - $ cd sqlite-3.6.22 + $ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz + $ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz + $ cd sqlite-3.6.23.1 Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable needs to be customized so that SQLite knows to build the R*Tree module:: @@ -398,7 +398,7 @@ needs to be customized so that SQLite knows to build the R*Tree module:: .. note:: If using Ubuntu, installing a newer SQLite from source can be very difficult - because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which + because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which many other packages depend on. Unfortunately, the best solution at this time is to overwrite the existing library by adding ``--prefix=/usr`` to the ``configure`` command. @@ -420,7 +420,7 @@ SpatiaLite library source and tools bundle from the `download page`__:: $ tar xzf spatialite-tools-2.3.1.tar.gz Prior to attempting to build, please read the important notes below to see if -customization of the ``configure`` command is necessary. If not, then run the +customization of the ``configure`` command is necessary. If not, then run the ``configure`` script, make, and install for the SpatiaLite library:: $ cd libspatialite-amalgamation-2.3.1 @@ -431,7 +431,7 @@ customization of the ``configure`` command is necessary. If not, then run the Finally, do the same for the SpatiaLite tools:: - $ cd spatialite-tools-2.3.1 + $ cd spatialite-tools-2.3.1 $ ./configure # May need to modified, see notes below. $ make $ sudo make install @@ -440,21 +440,18 @@ Finally, do the same for the SpatiaLite tools:: .. note:: If you've installed GEOS and PROJ.4 from binary packages, you will have to specify - their paths when running the ``configure`` scripts for *both* the library and the - tools (the configure scripts look, by default, in ``/usr/local``). For example, + their paths when running the ``configure`` scripts for *both* the library and the + tools (the configure scripts look, by default, in ``/usr/local``). For example, on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be:: - + $ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib .. note:: - For Mac OS X users building from source, the SpatiaLite library *and* tools - need to be linked into the existing ``iconv`` library. While this happens - automatically on Linux, the ``configure`` scripts need to know about the - specific location on Mac OS X (via modification of the ``CFLAGS`` and - ``LDFLAGS`` environment variables prior to configuration):: + For Mac OS X users building from source, the SpatiaLite library *and* tools + need to have their ``target`` configured:: - $ CFLAGS=-I/usr/include LDFLAGS="-L/usr/lib -liconv" ./configure + $ ./configure --target=macosx __ http://www.gaia-gis.it/spatialite/sources.html @@ -466,7 +463,7 @@ pysqlite2 Because SpatiaLite must be loaded as an external extension, it requires the ``enable_load_extension`` method, which is only available in versions 2.5+. Thus, download pysqlite2 2.6, and untar:: - + $ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz $ tar xzf pysqlite-2.6.0.tar.gz $ cd pysqlite-2.6.0 @@ -487,7 +484,7 @@ to look like the following:: ``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs`` and ``library_dirs`` settings are uncommented and set to the appropriate path if the SQLite header files and libraries are not in ``/usr/include`` - and ``/usr/lib``, respectively. + and ``/usr/lib``, respectively. After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script to build and install:: @@ -503,7 +500,7 @@ Creating a Spatial Database Template for PostGIS ------------------------------------------------ Creating a spatial database with PostGIS is different than normal because -additional SQL must be loaded to enable spatial functionality. Because of +additional SQL must be loaded to enable spatial functionality. Because of the steps in this process, it's better to create a database template that can be reused later. @@ -521,7 +518,7 @@ user. For example, you can use the following to become the ``postgres`` user:: version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``. The example below assumes PostGIS 1.5, thus you may need to modify - ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific + ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific version of PostGIS you are using. Once you're a database super user, then you may execute the following commands @@ -601,7 +598,7 @@ __ http://www.gaia-gis.it/spatialite/resources.html Add ``django.contrib.gis`` to ``INSTALLED_APPS`` ------------------------------------------------ -Like other Django contrib applications, you will *only* need to add +Like other Django contrib applications, you will *only* need to add :mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings. This is the so that ``gis`` templates can be located -- if not done, then features such as the geographic admin or KML sitemaps will not function properly. @@ -633,7 +630,7 @@ Invoke the Django shell from your project and execute the In Django 1.1 the name of this function is ``add_postgis_srs``. This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent) -table, making it possible for the spatial database to transform coordinates in +table, making it possible for the spatial database to transform coordinates in this projection. You only need to execute this command *once* per spatial database. Troubleshooting @@ -643,8 +640,8 @@ If you can't find the solution to your problem here then participate in the community! You can: * Join the ``#geodjango`` IRC channel on FreeNode (may be accessed on the - web via `Mibbit`__). Please be patient and polite -- while you may not - get an immediate response, someone will attempt to answer your question + web via `Mibbit`__). Please be patient and polite -- while you may not + get an immediate response, someone will attempt to answer your question as soon as they see it. * Ask your question on the `GeoDjango`__ mailing list. * File a ticket on the `Django trac`__ if you think there's a bug. Make @@ -662,7 +659,7 @@ Library Environment Settings By far, the most common problem when installing GeoDjango is that the external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_ -Typically, the cause of this problem is that the operating system isn't aware +Typically, the cause of this problem is that the operating system isn't aware of the directory where the libraries built from source were installed. In general, the library path may be set on a per-user basis by setting @@ -673,9 +670,9 @@ system. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A user may set this environment variable to customize the library paths -they want to use. The typical library directory for software +they want to use. The typical library directory for software built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs -to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user +to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user could place the following in their bash profile:: export LD_LIBRARY_PATH=/usr/local/lib @@ -685,7 +682,7 @@ Setting System Library Path On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include additional paths from files in another directory, such as ``/etc/ld.so.conf.d``. -As the root user, add the custom library path (like ``/usr/local/lib``) on a +As the root user, add the custom library path (like ``/usr/local/lib``) on a new line in ``ld.so.conf``. This is *one* example of how to do so:: $ sudo echo /usr/local/lib >> /etc/ld.so.conf @@ -705,9 +702,9 @@ Install ``binutils`` GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python module) to discover libraries. The ``find_library`` routine uses a program -called ``objdump`` (part of the ``binutils`` package) to verify a shared +called ``objdump`` (part of the ``binutils`` package) to verify a shared library on GNU/Linux systems. Thus, if ``binutils`` is not installed on your -Linux system then Python's ctypes may not be able to find your library even if +Linux system then Python's ctypes may not be able to find your library even if your library path is set correctly and geospatial libraries were built perfectly. The ``binutils`` package may be installed on Debian and Ubuntu systems using the @@ -738,10 +735,10 @@ several different options for installing GeoDjango. These options are: .. note:: Currently, the easiest and recommended approach for installing GeoDjango - on OS X is to use the KyngChaos packages. + on OS X is to use the KyngChaos packages. -This section also includes instructions for installing an upgraded version -of :ref:`macosx_python` from packages provided by the Python Software +This section also includes instructions for installing an upgraded version +of :ref:`macosx_python` from packages provided by the Python Software Foundation, however, this is not required. .. _macosx_python: @@ -750,8 +747,8 @@ Python ^^^^^^ Although OS X comes with Python installed, users can use framework -installers (`2.5`__ and `2.6`__ are available) provided by -the Python Software Foundation. An advantage to using the installer is +installers (`2.5`__ and `2.6`__ are available) provided by +the Python Software Foundation. An advantage to using the installer is that OS X's Python will remain "pristine" for internal operating system use. @@ -759,7 +756,7 @@ __ http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg __ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg .. note:: - + You will need to modify the ``PATH`` environment variable in your ``.profile`` file so that the new version of Python is used when ``python`` is entered at the command-line:: @@ -771,15 +768,15 @@ __ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg KyngChaos Packages ^^^^^^^^^^^^^^^^^^ -William Kyngesburye provides a number of `geospatial library binary packages`__ -that make it simple to get GeoDjango installed on OS X without compiling +William Kyngesburye provides a number of `geospatial library binary packages`__ +that make it simple to get GeoDjango installed on OS X without compiling them from source. However, the `Apple Developer Tools`_ are still necessary for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS) -and :ref:`pysqlite2_kyngchaos` (for SpatiaLite). +and :ref:`pysqlite2_kyngchaos` (for SpatiaLite). .. note:: - SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section + SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section after installing the packages for additional instructions. Download the framework packages for: @@ -804,8 +801,8 @@ your ``.profile`` to be able to run the package programs from the command-line:: export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH export PATH=/usr/local/pgsql/bin:$PATH -__ http://www.kyngchaos.com/wiki/software:frameworks -__ http://www.kyngchaos.com/wiki/software:postgres +__ http://www.kyngchaos.com/software/frameworks +__ http://www.kyngchaos.com/software/postgres .. note:: @@ -837,7 +834,7 @@ described above, ``psycopg2`` may be installed using the following command:: pysqlite2 ~~~~~~~~~ -Follow the :ref:`pysqlite2` source install instructions, however, +Follow the :ref:`pysqlite2` source install instructions, however, when editing the ``setup.cfg`` use the following instead:: [build_ext] @@ -854,7 +851,7 @@ SpatiaLite When :ref:`create_spatialite_db`, the ``spatialite`` program is required. However, instead of attempting to compile the SpatiaLite tools from source, -download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a +download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a location available in your ``PATH``. For example:: $ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz @@ -890,9 +887,9 @@ __ http://www.finkproject.org/ MacPorts ^^^^^^^^ -`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh +`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh computers running OS X. Because MacPorts still builds the software from source, -the `Apple Developer Tools`_ are required. +the `Apple Developer Tools`_ are required. Summary:: @@ -901,7 +898,7 @@ Summary:: $ sudo port install proj $ sudo port install postgis $ sudo port install gdal - $ sudo port install libgeoip + $ sudo port install libgeoip .. note:: @@ -932,9 +929,9 @@ Ubuntu 8.04 and lower ~~~~~~~~~~~~~~ -The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages, -which is incompatible with GeoDjango. Thus, do *not* use the binary packages -for GEOS or PostGIS and build some prerequisites from source, per the instructions +The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages, +which is incompatible with GeoDjango. Thus, do *not* use the binary packages +for GEOS or PostGIS and build some prerequisites from source, per the instructions in this document; however, it is okay to use the PostgreSQL binary packages. For more details, please see the Debian instructions for :ref:`etch` below. @@ -973,11 +970,11 @@ Optional packages to consider: * ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation .. note:: - + The Ubuntu ``proj`` package does not come with the datum shifting files - installed, which will cause problems with the geographic admin because + installed, which will cause problems with the geographic admin because the ``null`` datum grid is not available for transforming geometries to the - spherical mercator projection. A solution is to download the + spherical mercator projection. A solution is to download the datum-shifting files, create the grid file, and install it yourself:: $ wget http://download.osgeo.org/proj/proj-datumgrid-1.4.tar.gz @@ -988,7 +985,7 @@ Optional packages to consider: $ sudo cp null /usr/share/proj Otherwise, the Ubuntu ``proj`` package is fine for general use as long as you - do not plan on doing any database transformation of geometries to the + do not plan on doing any database transformation of geometries to the Google projection (900913). .. note:: @@ -1035,14 +1032,14 @@ Optional packages: Source Packages ~~~~~~~~~~~~~~~ You will still have to install :ref:`geosbuild`, :ref:`proj4`, -:ref:`postgis`, and :ref:`gdalbuild` from source. Please follow the +:ref:`postgis`, and :ref:`gdalbuild` from source. Please follow the directions carefully. .. _lenny: 5.0 (Lenny) ^^^^^^^^^^^ -This version is comparable to Ubuntu :ref:`ibex`, so the command +This version is comparable to Ubuntu :ref:`ibex`, so the command is very similar:: $ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools @@ -1089,13 +1086,13 @@ Python ^^^^^^ First, download the `Python 2.6 installer`__ from the Python website. Next, -execute the installer and use defaults, e.g., keep 'Install for all users' +execute the installer and use defaults, e.g., keep 'Install for all users' checked and the installation path set as ``C:\Python26``. .. note:: You may already have a version of Python installed in ``C:\python`` as ESRI - products sometimes install a copy there. *You should still install a + products sometimes install a copy there. *You should still install a fresh version of Python 2.6.* __ http://python.org/ftp/python/2.6.2/python-2.6.2.msi @@ -1110,21 +1107,21 @@ the EnterpriseDB website. PostgreSQL 8.3 is required because PostGIS is not available yet for 8.4. -After downloading, simply click on the installer, follow the -on-screen directions, and keep the default options (e.g., keep the installation +After downloading, simply click on the installer, follow the +on-screen directions, and keep the default options (e.g., keep the installation path as ``C:\Program Files\PostgreSQL\8.3``). .. note:: - This PostgreSQL installation process will create both a new windows user to be the - 'postgres service account' and a special 'postgres superuser' to own the database - cluster. You will be prompted to set a password for both users (make sure to write - them down!). To see basic details on the 'service user' account right click on - 'My Computer' and select 'Manage' or go to: Control Panel -> Administrative Tools -> + This PostgreSQL installation process will create both a new windows user to be the + 'postgres service account' and a special 'postgres superuser' to own the database + cluster. You will be prompted to set a password for both users (make sure to write + them down!). To see basic details on the 'service user' account right click on + 'My Computer' and select 'Manage' or go to: Control Panel -> Administrative Tools -> Computer Management -> System Tools -> Local Users and Groups. -If installed successfully, the PostgreSQL server will run in the background each time -the system as started as a Windows service. When finished, the installer should launch +If installed successfully, the PostgreSQL server will run in the background each time +the system as started as a Windows service. When finished, the installer should launch the Application Stack Builder (ASB) -- use this to install PostGIS, see instructions below for more details. A 'PostgreSQL 8.3' start menu group should be created that contains shortcuts for the ASB and 'Command Prompt', which launches a terminal window @@ -1135,22 +1132,22 @@ __ http://www.enterprisedb.com/products/pgdownload.do#windows PostGIS ^^^^^^^ -From the Application Stack Builder (Programs -> PostgreSQL 8.3), select -'PostgreSQL Database Server 8.3 on port 5432' from the drop down menu. Next, +From the Application Stack Builder (Programs -> PostgreSQL 8.3), select +'PostgreSQL Database Server 8.3 on port 5432' from the drop down menu. Next, select 'PostGIS 1.3.6 for PostgreSQL 8.3' from the 'Spatial Extensions' tree -in the list. Select only the default options during install (do not uncheck +in the list. Select only the default options during install (do not uncheck the option to create a default PostGIS database). .. note:: - You will be prompted to enter your 'postgres superuser' password in the + You will be prompted to enter your 'postgres superuser' password in the 'Database Connection Information' dialog. psycopg2 ^^^^^^^^ The ``psycopg2`` Python module provides the interface between Python and the -PostgreSQL database. Download the `Windows installer`__ (v2.0.10) and run +PostgreSQL database. Download the `Windows installer`__ (v2.0.10) and run using the default settings. [#]_ __ http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.0.10.win32-py2.6-pg8.3.7-release.exe @@ -1163,31 +1160,31 @@ of the process for installing GeoDjango on Windows platforms. The installer automatically installs Django 1.1, GDAL 1.6.0, PROJ 4.6.1 (including datum grid files), and configures the necessary environment variables. -Once the installer has completed, log out and log back in so that the +Once the installer has completed, log out and log back in so that the modifications to the system environment variables take effect, and you should be good to go. .. note:: The installer modifies the system ``Path`` environment variable to - include ``C:\Program Files\PostgreSQL\8.3\bin`` and + include ``C:\Program Files\PostgreSQL\8.3\bin`` and ``C:\Program Files\GeoDjango\bin``. This is required so that Python may find the GEOS DLL provided by PostGIS and the GDAL DLL provided - by the installer. The installer also sets the ``GDAL_DATA`` and + by the installer. The installer also sets the ``GDAL_DATA`` and ``PROJ_LIB`` environment variables. __ http://geodjango.org/windows/GeoDjango_Installer.exe .. rubric:: Footnotes .. [#] The datum shifting files are needed for converting data to and from certain projections. - For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_ - requires the ``null`` grid file only included in the extra datum shifting files. + For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_ + requires the ``null`` grid file only included in the extra datum shifting files. It is easier to install the shifting files now, then to have debug a problem caused by their absence later. .. [#] Specifically, GeoDjango provides support for the `OGR <http://gdal.org/ogr>`_ library, a component of GDAL. .. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_. .. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_ - routine from ``ctypes.util`` to locate shared libraries. -.. [#] The ``psycopg2`` Windows installers are packaged and maintained by - `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. -.. [#] The source code for the installer is available in the `nsis_installer <http://geodjango.org/hg/nsis_installer/>`_ + routine from ``ctypes.util`` to locate shared libraries. +.. [#] The ``psycopg2`` Windows installers are packaged and maintained by + `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. +.. [#] The source code for the installer is available in the `nsis_installer <http://geodjango.org/hg/nsis_installer/>`_ GeoDjango mercurial repository. diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index a423259c11..0b09e176f6 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -14,7 +14,7 @@ vector spatial data files (e.g. shapefiles) intoto GeoDjango models. This utility grew out of the author's personal needs to eliminate the code repetition that went into pulling geometries and fields out of -a vector layer, converting to another coordinate system (e.g. WGS84), and +a vector layer, converting to another coordinate system (e.g. WGS84), and then inserting into a GeoDjango model. .. note:: @@ -27,7 +27,7 @@ then inserting into a GeoDjango model. that :class:`LayerMapping` is using too much memory, set :setting:`DEBUG` to ``False`` in your settings. When :setting:`DEBUG` is set to ``True``, Django :ref:`automatically logs <faq-see-raw-sql-queries>` - *every* SQL query -- thus, when SQL statements contain geometries, it is + *every* SQL query -- thus, when SQL statements contain geometries, it is easy to consume more memory than is typical. Example @@ -50,7 +50,7 @@ Example DATUM["WGS_1984", SPHEROID["WGS_1984",6378137,298.257223563]], PRIMEM["Greenwich",0], - UNIT["Degree",0.017453292519943295]] + UNIT["Degree",0.017453292519943295]] 2. Now we define our corresponding Django model (make sure to use ``syncdb``):: @@ -71,16 +71,16 @@ Example >>> mapping = {'name' : 'str', # The 'name' model field maps to the 'str' layer field. 'poly' : 'POLYGON', # For geometry fields use OGC name. } # The mapping is a dictionary - >>> lm = LayerMapping(TestGeo, 'test_poly.shp', mapping) - >>> lm.save(verbose=True) # Save the layermap, imports the data. + >>> lm = LayerMapping(TestGeo, 'test_poly.shp', mapping) + >>> lm.save(verbose=True) # Save the layermap, imports the data. Saved: Name: 1 Saved: Name: 2 Saved: Name: 3 Here, :class:`LayerMapping` just transformed the three geometries from the shapefile in their original spatial reference system (WGS84) to the spatial -reference system of the GeoDjango model (NAD83). If no spatial reference -system is defined for the layer, use the ``source_srs`` keyword with a +reference system of the GeoDjango model (NAD83). If no spatial reference +system is defined for the layer, use the ``source_srs`` keyword with a :class:`~django.contrib.gis.gdal.SpatialReference` object to specify one. ``LayerMapping`` API @@ -106,43 +106,43 @@ Argument Description model field is a geographic then it should correspond to the OGR geometry type, e.g., ``'POINT'``, ``'LINESTRING'``, ``'POLYGON'``. -================= ========================================================= +================= ========================================================= ===================== ===================================================== Keyword Arguments -===================== ===================================================== -``layer`` The index of the layer to use from the Data Source +===================== ===================================================== +``layer`` The index of the layer to use from the Data Source (defaults to 0) - -``source_srs`` Use this to specify the source SRS manually (for - example, some shapefiles don't come with a '.prj' - file). An integer SRID, WKT or PROJ.4 strings, and - :class:`django.contrib.gis.gdal.SpatialReference` + +``source_srs`` Use this to specify the source SRS manually (for + example, some shapefiles don't come with a '.prj' + file). An integer SRID, WKT or PROJ.4 strings, and + :class:`django.contrib.gis.gdal.SpatialReference` objects are accepted. - -``encoding`` Specifies the character set encoding of the strings - in the OGR data source. For example, ``'latin-1'``, - ``'utf-8'``, and ``'cp437'`` are all valid encoding + +``encoding`` Specifies the character set encoding of the strings + in the OGR data source. For example, ``'latin-1'``, + ``'utf-8'``, and ``'cp437'`` are all valid encoding parameters. - -``transaction_mode`` May be ``'commit_on_success'`` (default) or + +``transaction_mode`` May be ``'commit_on_success'`` (default) or ``'autocommit'``. - -``transform`` Setting this to False will disable coordinate + +``transform`` Setting this to False will disable coordinate transformations. In other words, geometries will be inserted into the database unmodified from their original state in the data source. - + ``unique`` Setting this to the name, or a tuple of names, from the given model will create models unique - only to the given name(s). Geometries will from - each feature will be added into the collection - associated with the unique model. Forces + only to the given name(s). Geometries will from + each feature will be added into the collection + associated with the unique model. Forces the transaction mode to be ``'autocommit'``. ``using`` New in version 1.2. Sets the database to use when importing spatial data. Default is ``'default'`` -===================== ===================================================== +===================== ===================================================== ``save()`` Keyword Arguments ---------------------------- @@ -156,42 +156,42 @@ specific feature ranges. =========================== ================================================= Save Keyword Arguments Description =========================== ================================================= -``fid_range`` May be set with a slice or tuple of - (begin, end) feature ID's to map from +``fid_range`` May be set with a slice or tuple of + (begin, end) feature ID's to map from the data source. In other words, this - keyword enables the user to selectively + keyword enables the user to selectively import a subset range of features in the geographic data source. ``progress`` When this keyword is set, status information - will be printed giving the number of features - processed and successfully saved. By default, + will be printed giving the number of features + processed and successfully saved. By default, progress information will be printed every 1000 - features processed, however, this default may - be overridden by setting this keyword with an + features processed, however, this default may + be overridden by setting this keyword with an integer for the desired interval. -``silent`` By default, non-fatal error notifications are - printed to ``sys.stdout``, but this keyword may +``silent`` By default, non-fatal error notifications are + printed to ``sys.stdout``, but this keyword may be set to disable these notifications. -``step`` If set with an integer, transactions will - occur at every step interval. For example, if - ``step=1000``, a commit would occur after the +``step`` If set with an integer, transactions will + occur at every step interval. For example, if + ``step=1000``, a commit would occur after the 1,000th feature, the 2,000th feature etc. -``stream`` Status information will be written to this file - handle. Defaults to using ``sys.stdout``, but +``stream`` Status information will be written to this file + handle. Defaults to using ``sys.stdout``, but any object with a ``write`` method is supported. -``strict`` Execution of the model mapping will cease upon +``strict`` Execution of the model mapping will cease upon the first error encountered. The default value (``False``) behavior is to attempt to continue. -``verbose`` If set, information will be printed - subsequent to each model save +``verbose`` If set, information will be printed + subsequent to each model save executed on the database. =========================== ================================================= @@ -213,7 +213,7 @@ If you encounter the following error when using ``LayerMapping`` and MySQL:: OperationalError: (1153, "Got a packet bigger than 'max_allowed_packet' bytes") Then the solution is to increase the value of the ``max_allowed_packet`` -setting in your MySQL configuration. For example, the default value may +setting in your MySQL configuration. For example, the default value may be something low like one megabyte -- the setting may be modified in MySQL's configuration file (``my.cnf``) in the ``[mysqld]`` section:: diff --git a/docs/ref/contrib/gis/measure.txt b/docs/ref/contrib/gis/measure.txt index 8b9629ef80..6971788b4e 100644 --- a/docs/ref/contrib/gis/measure.txt +++ b/docs/ref/contrib/gis/measure.txt @@ -7,17 +7,17 @@ Measurement Objects .. module:: django.contrib.gis.measure :synopsis: GeoDjango's distance and area measurment objects. -The :mod:`django.contrib.gis.measure` module contains objects that allow -for convenient representation of distance and area units of measure. [#]_ -Specifically, it implements two objects, :class:`Distance` and -:class:`Area` -- both of which may be accessed via the +The :mod:`django.contrib.gis.measure` module contains objects that allow +for convenient representation of distance and area units of measure. [#]_ +Specifically, it implements two objects, :class:`Distance` and +:class:`Area` -- both of which may be accessed via the :class:`D` and :class:`A` convenience aliases, respectively. Example ======= -:class:`Distance` objects may be instantiated using a keyword argument indicating the -context of the units. In the example below, two different distance objects are +:class:`Distance` objects may be instantiated using a keyword argument indicating the +context of the units. In the example below, two different distance objects are instantiated in units of kilometers (``km``) and miles (``mi``):: >>> from django.contrib.gis.measure import Distance, D @@ -40,7 +40,7 @@ Moreover, arithmetic operations may be performed between the distance objects:: >>> print d1 + d2 # Adding 5 miles to 5 kilometers - 13.04672 km + 13.04672 km >>> print d2 - d1 # Subtracting 5 kilometers from 5 miles 1.89314403881 mi @@ -67,7 +67,7 @@ Supported units ================================= ======================================== Unit Attribute Full name or alias(es) ================================= ======================================== -``km`` Kilometre, Kilometer +``km`` Kilometre, Kilometer ``mi`` Mile ``m`` Meter, Metre ``yd`` Yard @@ -163,7 +163,7 @@ Measurement API 12.949940551680001 .. classmethod:: unit_attname(unit_name) - + Returns the area unit attribute name for the given full unit name. For example:: @@ -175,6 +175,6 @@ Measurement API Alias for :class:`Area` class. .. rubric:: Footnotes -.. [#] `Robert Coup <http://koordinates.com/>`_ is the initial author of the measure objects, - and was inspired by Brian Beck's work in `geopy <http://code.google.com/p/geopy/>`_ +.. [#] `Robert Coup <http://koordinates.com/>`_ is the initial author of the measure objects, + and was inspired by Brian Beck's work in `geopy <http://code.google.com/p/geopy/>`_ and Geoff Biggs' PhD work on dimensioned units for robotics. diff --git a/docs/ref/contrib/gis/model-api.txt b/docs/ref/contrib/gis/model-api.txt index 7c83a7e267..cf73747463 100644 --- a/docs/ref/contrib/gis/model-api.txt +++ b/docs/ref/contrib/gis/model-api.txt @@ -8,11 +8,11 @@ GeoDjango Model API :synopsis: GeoDjango model and field API. This document explores the details of the GeoDjango Model API. Throughout this -section, we'll be using the following geographic model of a `ZIP code`__ as our +section, we'll be using the following geographic model of a `ZIP code`__ as our example:: from django.contrib.gis.db import models - + class Zipcode(models.Model): code = models.CharField(max_length=5) poly = models.PolygonField() @@ -23,7 +23,7 @@ __ http://en.wikipedia.org/wiki/ZIP_code Geometry Field Types ==================== -Each of the following geometry field types correspond with the +Each of the following geometry field types correspond with the OpenGIS Simple Features specification [#fnogc]_. ``GeometryField`` @@ -92,7 +92,7 @@ Selecting an SRID ^^^^^^^^^^^^^^^^^ Choosing an appropriate SRID for your model is an important decision that the -developer should consider carefully. The SRID is an integer specifier that +developer should consider carefully. The SRID is an integer specifier that corresponds to the projection system that will be used to interpret the data in the spatial database. [#fnsrid]_ Projection systems give the context to the coordinates that specify a location. Although the details of `geodesy`__ are @@ -105,7 +105,7 @@ location on the earth's surface. However, latitude and longitude are angles, not distances. [#fnharvard]_ In other words, while the shortest path between two points on a flat surface is a straight line, the shortest path between two points on a curved surface (such as the earth) is an *arc* of a `great circle`__. [#fnthematic]_ Thus, -additional computation is required to obtain distances in planar units (e.g., +additional computation is required to obtain distances in planar units (e.g., kilometers and miles). Using a geographic coordinate system may introduce complications for the developer later on. For example, PostGIS versions 1.4 and below do not have the capability to perform distance calculations between @@ -113,12 +113,12 @@ non-point geometries using geographic coordinate systems, e.g., constructing a query to find all points within 5 miles of a county boundary stored as WGS84. [#fndist]_ -Portions of the earth's surface may projected onto a two-dimensional, or +Portions of the earth's surface may projected onto a two-dimensional, or Cartesian, plane. Projected coordinate systems are especially convenient for region-specific applications, e.g., if you know that your database will -only cover geometries in `North Kansas`__, then you may consider using projection -system specific to that region. Moreover, projected coordinate systems are -defined in Cartesian units (such as meters or feet), easing distance +only cover geometries in `North Kansas`__, then you may consider using projection +system specific to that region. Moreover, projected coordinate systems are +defined in Cartesian units (such as meters or feet), easing distance calculations. .. note:: @@ -131,7 +131,7 @@ calculations. Additional Resources: -* `spatialreference.org`__: A Django-powered database of spatial reference +* `spatialreference.org`__: A Django-powered database of spatial reference systems. * `The State Plane Coordinate System`__: A website covering the various projection systems used in the United States. Much of the U.S. spatial @@ -150,7 +150,7 @@ __ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinate .. attribute:: GeometryField.spatial_index Defaults to ``True``. Creates a spatial index for the given geometry -field. +field. .. note:: @@ -185,7 +185,7 @@ three-dimensonal support. .. attribute:: GeometryField.geography If set to ``True``, this option will create a database column of -type geography, rather than geometry. Please refer to the +type geography, rather than geometry. Please refer to the :ref:`geography type <geography-type>` section below for more details. @@ -212,7 +212,7 @@ to degrees if called on a geometry column in WGS84). Because geography calculations involve more mathematics, only a subset of the PostGIS spatial lookups are available for the geography type. Practically, this means that in addition to the :ref:`distance lookups <distance-lookups>` -only the following additional :ref:`spatial lookups <spatial-lookups>` are +only the following additional :ref:`spatial lookups <spatial-lookups>` are available for geography columns: * :lookup:`bboverlaps` @@ -231,13 +231,13 @@ determining `when to use geography data type over geometry data type .. currentmodule:: django.contrib.gis.db.models .. class:: GeoManager -In order to conduct geographic queries, each geographic model requires +In order to conduct geographic queries, each geographic model requires a ``GeoManager`` model manager. This manager allows for the proper SQL -construction for geographic queries; thus, without it, all geographic filters +construction for geographic queries; thus, without it, all geographic filters will fail. It should also be noted that ``GeoManager`` is required even if the -model does not have a geographic field itself, e.g., in the case of a -``ForeignKey`` relation to a model with a geographic field. For example, -if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode`` +model does not have a geographic field itself, e.g., in the case of a +``ForeignKey`` relation to a model with a geographic field. For example, +if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode`` model:: from django.contrib.gis.db import models @@ -251,7 +251,7 @@ model:: zipcode = models.ForeignKey(Zipcode) objects = models.GeoManager() -The geographic manager is needed to do spatial queries on related ``Zipcode`` objects, +The geographic manager is needed to do spatial queries on related ``Zipcode`` objects, for example:: qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)') @@ -260,7 +260,7 @@ for example:: .. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999). .. [#fnogcsrid] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems). .. [#fnsrid] Typically, SRID integer corresponds to an EPSG (`European Petroleum Survey Group <http://www.epsg.org>`_) identifier. However, it may also be associated with custom projections defined in spatial database's spatial reference systems table. -.. [#fnharvard] Harvard Graduate School of Design, `An Overview of Geodesy and Geographic Referencing Systems <http://www.gsd.harvard.edu/gis/manual/projections/fundamentals/>`_. This is an excellent resource for an overview of principles relating to geographic and Cartesian coordinate systems. +.. [#fnharvard] Harvard Graduate School of Design, `An Overview of Geodesy and Geographic Referencing Systems <http://www.gsd.harvard.edu/gis/manual/projections/fundamentals/>`_. This is an excellent resource for an overview of principles relating to geographic and Cartesian coordinate systems. .. [#fnthematic] Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler, & Hugh H. Howard, *Thematic Cartography and Geographic Visualization* (Prentice Hall, 2nd edition), at Ch. 7.1.3. .. [#fndist] This limitation does not apply to PostGIS 1.5. It should be noted that even in previous versions of PostGIS, this isn't impossible using GeoDjango; you could for example, take a known point in a projected coordinate system, buffer it to the appropriate radius, and then perform an intersection operation with the buffer transformed to the geographic coordinate system. .. [#fngeography] Please refer to the `PostGIS Geography Type <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_Geography>`_ documentation for more details. diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt index b2513f670b..2e81510cd9 100644 --- a/docs/ref/contrib/gis/testing.txt +++ b/docs/ref/contrib/gis/testing.txt @@ -6,7 +6,7 @@ Testing GeoDjango Apps In Django 1.2, the addition of :ref:`spatial-backends` simplified the process of testing GeoDjango applications. Specifically, testing -GeoDjango applications is now the same as :ref:`topics-testing`. +GeoDjango applications is now the same as :doc:`/topics/testing`. Included in this documentation are some additional notes and settings for :ref:`testing-postgis` and :ref:`testing-spatialite` users. @@ -133,7 +133,7 @@ You will need to download the `initialization SQL`__ script for SpatiaLite:: If ``init_spatialite-2.3.sql`` is in the same path as your project's ``manage.py``, then all you have to do is:: - $ python manage.py test + $ python manage.py test Settings -------- @@ -166,9 +166,9 @@ must be used. To use this runner, configure :setting:`TEST_RUNNER` as follows:: .. note:: - In order to create a spatial database, the :setting:`DATABASE_USER` setting - (or :setting:`TEST_DATABASE_USER`, if optionally defined on Oracle) requires - elevated privileges. When using PostGIS or MySQL, the database user + In order to create a spatial database, the :setting:`USER` setting + (or :setting:`TEST_USER`, if optionally defined on Oracle) requires + elevated privileges. When using PostGIS or MySQL, the database user must have at least the ability to create databases. When testing on Oracle, the user should be a superuser. diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 5b535186f8..3a56c2e7c0 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -15,8 +15,8 @@ geographic web applications, like location-based services. Some features includ data formats. * Editing of geometry fields inside the admin. -This tutorial assumes a familiarity with Django; thus, if you're brand new to -Django please read through the :ref:`regular tutorial <intro-tutorial01>` to introduce +This tutorial assumes a familiarity with Django; thus, if you're brand new to +Django please read through the :doc:`regular tutorial </intro/tutorial01>` to introduce yourself with basic Django concepts. .. note:: @@ -27,12 +27,12 @@ yourself with basic Django concepts. This tutorial is going to guide you through guide the user through the creation of a geographic web application for viewing the `world borders`_. [#]_ Some of -the code used in this tutorial is taken from and/or inspired by the +the code used in this tutorial is taken from and/or inspired by the `GeoDjango basic apps`_ project. [#]_ .. note:: - Proceed through the tutorial sections sequentially for step-by-step + Proceed through the tutorial sections sequentially for step-by-step instructions. .. _OGC: http://www.opengeospatial.org/ @@ -51,11 +51,11 @@ Create a Spatial Database are already built into the database. First, a spatial database needs to be created for our project. If using -PostgreSQL and PostGIS, then the following commands will +PostgreSQL and PostGIS, then the following commands will create the database from a :ref:`spatial database template <spatialdb_template>`:: $ createdb -T template_postgis geodjango - + .. note:: This command must be issued by a database user that has permissions to @@ -65,9 +65,9 @@ create the database from a :ref:`spatial database template <spatialdb_template>` $ sudo su - postgres $ createuser --createdb geo $ exit - + Replace ``geo`` to correspond to the system login user name will be - connecting to the database. For example, ``johndoe`` if that is the + connecting to the database. For example, ``johndoe`` if that is the system user that will be running GeoDjango. Users of SQLite and SpatiaLite should consult the instructions on how @@ -92,7 +92,7 @@ Configure ``settings.py`` The ``geodjango`` project settings are stored in the ``settings.py`` file. Edit the database connection settings appropriately:: - DATABASES = { + DATABASES = { 'default': { 'ENGINE': 'django.contrib.gis.db.backends.postgis', 'NAME': 'geodjango', @@ -104,7 +104,7 @@ the database connection settings appropriately:: These database settings are for Django 1.2 and above. -In addition, modify the :setting:`INSTALLED_APPS` setting to include +In addition, modify the :setting:`INSTALLED_APPS` setting to include :mod:`django.contrib.admin`, :mod:`django.contrib.gis`, and ``world`` (our newly created application):: @@ -142,8 +142,8 @@ unzipped the world borders data set includes files with the following extensions * ``.shp``: Holds the vector data for the world borders geometries. * ``.shx``: Spatial index file for geometries stored in the ``.shp``. -* ``.dbf``: Database file for holding non-geometric attribute data - (e.g., integer and character fields). +* ``.dbf``: Database file for holding non-geometric attribute data + (e.g., integer and character fields). * ``.prj``: Contains the spatial reference information for the geographic data stored in the shapefile. @@ -153,7 +153,7 @@ __ http://en.wikipedia.org/wiki/Shapefile Use ``ogrinfo`` to examine spatial data --------------------------------------- -The GDAL ``ogrinfo`` utility is excellent for examining metadata about +The GDAL ``ogrinfo`` utility is excellent for examining metadata about shapefiles (or other vector data sources):: $ ogrinfo world/data/TM_WORLD_BORDERS-0.3.shp @@ -192,13 +192,13 @@ and use the ``-so`` option to get only important summary information:: LAT: Real (7.3) This detailed summary information tells us the number of features in the layer -(246), the geographical extent, the spatial reference system ("SRS WKT"), +(246), the geographical extent, the spatial reference system ("SRS WKT"), as well as detailed information for each attribute field. For example, ``FIPS: String (2.0)`` indicates that there's a ``FIPS`` character field with a maximum length of 2; similarly, ``LON: Real (8.3)`` is a floating-point field that holds a maximum of 8 digits up to three decimal places. Although this information may be found right on the `world borders`_ website, this shows -you how to determine this information yourself when such metadata is not +you how to determine this information yourself when such metadata is not provided. Geographic Models @@ -213,7 +213,7 @@ create a GeoDjango model to represent this data:: from django.contrib.gis.db import models class WorldBorders(models.Model): - # Regular Django fields corresponding to the attributes in the + # Regular Django fields corresponding to the attributes in the # world borders shapefile. name = models.CharField(max_length=50) area = models.IntegerField() @@ -227,7 +227,7 @@ create a GeoDjango model to represent this data:: lon = models.FloatField() lat = models.FloatField() - # GeoDjango-specific: a geometry field (MultiPolygonField), and + # GeoDjango-specific: a geometry field (MultiPolygonField), and # overriding the default manager with a GeoManager instance. mpoly = models.MultiPolygonField() objects = models.GeoManager() @@ -235,23 +235,23 @@ create a GeoDjango model to represent this data:: # So the model is pluralized correctly in the admin. class Meta: verbose_name_plural = "World Borders" - - # Returns the string representation of the model. + + # Returns the string representation of the model. def __unicode__(self): return self.name Two important things to note: 1. The ``models`` module is imported from :mod:`django.contrib.gis.db`. -2. The model overrides its default manager with +2. The model overrides its default manager with :class:`~django.contrib.gis.db.models.GeoManager`; this is *required* - to perform spatial queries. + to perform spatial queries. When declaring a geometry field on your model the default spatial reference system is WGS84 (meaning the `SRID`__ is 4326) -- in other words, the field coordinates are in longitude/latitude pairs in units of degrees. If you want the coordinate system to be different, then SRID of the geometry field may be customized by setting the ``srid`` -with an integer corresponding to the coordinate system of your choice. +with an integer corresponding to the coordinate system of your choice. __ http://en.wikipedia.org/wiki/SRID @@ -259,7 +259,7 @@ Run ``syncdb`` -------------- After you've defined your model, it needs to be synced with the spatial database. -First, let's look at the SQL that will generate the table for the ``WorldBorders`` +First, let's look at the SQL that will generate the table for the ``WorldBorders`` model:: $ python manage.py sqlall world @@ -295,7 +295,7 @@ If satisfied, you may then create this table in the database by running the Installing custom SQL for world.WorldBorders model The ``syncdb`` command may also prompt you to create an admin user; go ahead and -do so (not required now, may be done at any point in the future using the +do so (not required now, may be done at any point in the future using the ``createsuperuser`` management command). Importing Spatial Data @@ -303,11 +303,11 @@ Importing Spatial Data This section will show you how to take the data from the world borders shapefile and import it into GeoDjango models using the :ref:`ref-layermapping`. -There are many different different ways to import data in to a +There are many different different ways to import data in to a spatial database -- besides the tools included within GeoDjango, you may also use the following to populate your spatial database: -* `ogr2ogr`_: Command-line utility, included with GDAL, that +* `ogr2ogr`_: Command-line utility, included with GDAL, that supports loading a multitude of vector data formats into the PostGIS, MySQL, and Oracle spatial databases. * `shp2pgsql`_: This utility is included with PostGIS and only supports @@ -339,7 +339,7 @@ tutorial, then we can determine the path using Python's built-in >>> world_shp = os.path.abspath(os.path.join(os.path.dirname(world.__file__), ... 'data/TM_WORLD_BORDERS-0.3.shp')) -Now, the world borders shapefile may be opened using GeoDjango's +Now, the world borders shapefile may be opened using GeoDjango's :class:`~django.contrib.gis.gdal.DataSource` interface:: >>> from django.contrib.gis.gdal import * @@ -347,7 +347,7 @@ Now, the world borders shapefile may be opened using GeoDjango's >>> print ds / ... /geodjango/world/data/TM_WORLD_BORDERS-0.3.shp (ESRI Shapefile) -Data source objects can have different layers of geospatial features; however, +Data source objects can have different layers of geospatial features; however, shapefiles are only allowed to have one layer:: >>> print len(ds) @@ -367,10 +367,10 @@ contains:: .. note:: Unfortunately the shapefile data format does not allow for greater - specificity with regards to geometry types. This shapefile, like + specificity with regards to geometry types. This shapefile, like many others, actually includes ``MultiPolygon`` geometries in its features. You need to watch out for this when creating your models - as a GeoDjango ``PolygonField`` will not accept a ``MultiPolygon`` + as a GeoDjango ``PolygonField`` will not accept a ``MultiPolygon`` type geometry -- thus a ``MultiPolygonField`` is used in our model's definition instead. @@ -391,7 +391,7 @@ system associated with it -- if it does, the ``srs`` attribute will return a Here we've noticed that the shapefile is in the popular WGS84 spatial reference system -- in other words, the data uses units of degrees longitude and latitude. -In addition, shapefiles also support attribute fields that may contain +In addition, shapefiles also support attribute fields that may contain additional data. Here are the fields on the World Borders layer: >>> print lyr.fields @@ -403,8 +403,8 @@ a string) associated with each of the fields: >>> [fld.__name__ for fld in lyr.field_types] ['OFTString', 'OFTString', 'OFTString', 'OFTInteger', 'OFTString', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTReal', 'OFTReal'] -You can iterate over each feature in the layer and extract information from both -the feature's geometry (accessed via the ``geom`` attribute) as well as the +You can iterate over each feature in the layer and extract information from both +the feature's geometry (accessed via the ``geom`` attribute) as well as the feature's attribute fields (whose **values** are accessed via ``get()`` method):: @@ -427,7 +427,7 @@ And individual features may be retrieved by their feature ID:: >>> print feat.get('NAME') San Marino -Here the boundary geometry for San Marino is extracted and looking +Here the boundary geometry for San Marino is extracted and looking exported to WKT and GeoJSON:: >>> geom = feat.geom @@ -465,7 +465,7 @@ We're going to dive right in -- create a file called ``load.py`` inside the world_shp = os.path.abspath(os.path.join(os.path.dirname(__file__), 'data/TM_WORLD_BORDERS-0.3.shp')) def run(verbose=True): - lm = LayerMapping(WorldBorders, world_shp, world_mapping, + lm = LayerMapping(WorldBorders, world_shp, world_mapping, transform=False, encoding='iso-8859-1') lm.save(strict=True, verbose=verbose) @@ -473,8 +473,8 @@ We're going to dive right in -- create a file called ``load.py`` inside the A few notes about what's going on: * Each key in the ``world_mapping`` dictionary corresponds to a field in the - ``WorldBorders`` model, and the value is the name of the shapefile field - that data will be loaded from. + ``WorldBorders`` model, and the value is the name of the shapefile field + that data will be loaded from. * The key ``mpoly`` for the geometry field is ``MULTIPOLYGON``, the geometry type we wish to import as. Even if simple polygons are encountered in the shapefile they will automatically be converted into collections prior @@ -503,10 +503,10 @@ do the work:: Try ``ogrinspect`` ------------------ -Now that you've seen how to define geographic models and import data with the +Now that you've seen how to define geographic models and import data with the :ref:`ref-layermapping`, it's possible to further automate this process with use of the :djadmin:`ogrinspect` management command. The :djadmin:`ogrinspect` -command introspects a GDAL-supported vector data source (e.g., a shapefile) and +command introspects a GDAL-supported vector data source (e.g., a shapefile) and generates a model definition and ``LayerMapping`` dictionary automatically. The general usage of the command goes as follows:: @@ -525,13 +525,13 @@ and mapping dictionary created above, automatically:: A few notes about the command-line options given above: * The ``--srid=4326`` option sets the SRID for the geographic field. -* The ``--mapping`` option tells ``ogrinspect`` to also generate a +* The ``--mapping`` option tells ``ogrinspect`` to also generate a mapping dictionary for use with :class:`~django.contrib.gis.utils.LayerMapping`. * The ``--multi`` option is specified so that the geographic field is a :class:`~django.contrib.gis.db.models.MultiPolygonField` instead of just a :class:`~django.contrib.gis.db.models.PolygonField`. -The command produces the following output, which may be copied +The command produces the following output, which may be copied directly into the ``models.py`` of a GeoDjango application:: # This is an auto-generated Django model module created by ogrinspect. @@ -584,7 +584,7 @@ Now, define a point of interest [#]_:: >>> pnt_wkt = 'POINT(-95.3385 29.7245)' The ``pnt_wkt`` string represents the point at -95.3385 degrees longitude, -and 29.7245 degrees latitude. The geometry is in a format known as +and 29.7245 degrees latitude. The geometry is in a format known as Well Known Text (WKT), an open standard issued by the Open Geospatial Consortium (OGC). [#]_ Import the ``WorldBorders`` model, and perform a ``contains`` lookup using the ``pnt_wkt`` as the parameter:: @@ -611,7 +611,7 @@ available -- the :ref:`ref-gis-db-api` documentation has more. Automatic Spatial Transformations --------------------------------- -When querying the spatial database GeoDjango automatically transforms +When querying the spatial database GeoDjango automatically transforms geometries if they're in a different coordinate system. In the following example, the coordinate will be expressed in terms of `EPSG SRID 32140`__, a coordinate system specific to south Texas **only** and in units of @@ -634,26 +634,26 @@ of abstraction:: ('SELECT "world_worldborders"."id", "world_worldborders"."name", "world_worldborders"."area", "world_worldborders"."pop2005", "world_worldborders"."fips", "world_worldborders"."iso2", "world_worldborders"."iso3", "world_worldborders"."un", "world_worldborders"."region", - "world_worldborders"."subregion", "world_worldborders"."lon", "world_worldborders"."lat", - "world_worldborders"."mpoly" FROM "world_worldborders" + "world_worldborders"."subregion", "world_worldborders"."lon", "world_worldborders"."lat", + "world_worldborders"."mpoly" FROM "world_worldborders" WHERE ST_Intersects("world_worldborders"."mpoly", ST_Transform(%s, 4326))', (<django.contrib.gis.db.backend.postgis.adaptor.PostGISAdaptor object at 0x25641b0>,)) >>> qs # printing evaluates the queryset - [<WorldBorders: United States>] + [<WorldBorders: United States>] __ http://spatialreference.org/ref/epsg/32140/ Lazy Geometries --------------- Geometries come to GeoDjango in a standardized textual representation. Upon -access of the geometry field, GeoDjango creates a `GEOS geometry object <ref-geos>`, -exposing powerful functionality, such as serialization properties for +access of the geometry field, GeoDjango creates a `GEOS geometry object <ref-geos>`, +exposing powerful functionality, such as serialization properties for popular geospatial formats:: >>> sm = WorldBorders.objects.get(name='San Marino') >>> sm.mpoly <MultiPolygon object at 0x24c6798> - >>> sm.mpoly.wkt # WKT + >>> sm.mpoly.wkt # WKT MULTIPOLYGON (((12.4157980000000006 43.9579540000000009, 12.4505540000000003 43.9797209999999978, ... >>> sm.mpoly.wkb # WKB (as Python binary buffer) <read-only buffer for 0x1fe2c70, size -1, offset 0 at 0x2564c40> @@ -682,16 +682,16 @@ Google Geographic Admin ---------------- -GeoDjango extends :ref:`Django's admin application <ref-contrib-admin>` to -enable support for editing geometry fields. +GeoDjango extends :doc:`Django's admin application </ref/contrib/admin/index>` +to enable support for editing geometry fields. Basics ^^^^^^ -GeoDjango also supplements the Django admin by allowing users to create +GeoDjango also supplements the Django admin by allowing users to create and modify geometries on a JavaScript slippy map (powered by `OpenLayers`_). -Let's dive in again -- create a file called ``admin.py`` inside the +Let's dive in again -- create a file called ``admin.py`` inside the ``world`` application, and insert the following:: from django.contrib.gis import admin diff --git a/docs/ref/contrib/humanize.txt b/docs/ref/contrib/humanize.txt index 07a62a7fbe..17db3c2535 100644 --- a/docs/ref/contrib/humanize.txt +++ b/docs/ref/contrib/humanize.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-humanize: - ======================== django.contrib.humanize ======================== diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt index bb470e3041..90edf72c94 100644 --- a/docs/ref/contrib/index.txt +++ b/docs/ref/contrib/index.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-index: - ==================== ``contrib`` packages ==================== @@ -35,6 +33,7 @@ those packages have. gis/index humanize localflavor + markup messages redirects sitemaps @@ -46,8 +45,8 @@ admin ===== The automatic Django administrative interface. For more information, see -:ref:`Tutorial 2 <intro-tutorial02>` and the -:ref:`admin documentation <ref-contrib-admin>`. +:doc:`Tutorial 2 </intro/tutorial02>` and the +:doc:`admin documentation </ref/contrib/admin/index>`. Requires the auth_ and contenttypes_ contrib packages to be installed. @@ -56,16 +55,16 @@ auth Django's authentication framework. -See :ref:`topics-auth`. +See :doc:`/topics/auth`. comments ======== .. versionchanged:: 1.0 - The comments application has been rewriten. See :ref:`ref-contrib-comments-upgrade` + The comments application has been rewriten. See :doc:`/ref/contrib/comments/upgrade` for information on howto upgrade. -A simple yet flexible comments system. See :ref:`ref-contrib-comments-index`. +A simple yet flexible comments system. See :doc:`/ref/contrib/comments/index`. contenttypes ============ @@ -73,21 +72,21 @@ contenttypes A light framework for hooking into "types" of content, where each installed Django model is a separate content type. -See the :ref:`contenttypes documentation <ref-contrib-contenttypes>`. +See the :doc:`contenttypes documentation </ref/contrib/contenttypes>`. csrf ==== A middleware for preventing Cross Site Request Forgeries -See the :ref:`csrf documentation <ref-contrib-csrf>`. +See the :doc:`csrf documentation </ref/contrib/csrf>`. flatpages ========= A framework for managing simple "flat" HTML content in a database. -See the :ref:`flatpages documentation <ref-contrib-flatpages>`. +See the :doc:`flatpages documentation </ref/contrib/flatpages>`. Requires the sites_ contrib package to be installed as well. @@ -103,14 +102,14 @@ An abstraction of the following workflow: "Display an HTML form, force a preview, then do something with the submission." -See the :ref:`form preview documentation <ref-contrib-formtools-form-preview>`. +See the :doc:`form preview documentation </ref/contrib/formtools/form-preview>`. django.contrib.formtools.wizard -------------------------------- Splits forms across multiple Web pages. -See the :ref:`form wizard documentation <ref-contrib-formtools-form-wizard>`. +See the :doc:`form wizard documentation </ref/contrib/formtools/form-wizard>`. gis ==== @@ -118,14 +117,14 @@ gis A world-class geospatial framework built on top of Django, that enables storage, manipulation and display of spatial data. -See the :ref:`ref-contrib-gis` documentation for more. +See the :doc:`/ref/contrib/gis/index` documentation for more. humanize ======== A set of Django template filters useful for adding a "human touch" to data. -See the :ref:`humanize documentation <ref-contrib-humanize>`. +See the :doc:`humanize documentation </ref/contrib/humanize>`. localflavor =========== @@ -134,45 +133,14 @@ A collection of various Django snippets that are useful only for a particular country or culture. For example, ``django.contrib.localflavor.us.forms`` contains a ``USZipCodeField`` that you can use to validate U.S. zip codes. -See the :ref:`localflavor documentation <ref-contrib-localflavor>`. - -.. _ref-contrib-markup: +See the :doc:`localflavor documentation </ref/contrib/localflavor>`. markup ====== -A collection of template filters that implement common markup languages: - - * ``textile`` -- implements `Textile`_ -- requires `PyTextile`_ - * ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_ - * ``restructuredtext`` -- implements `ReST (ReStructured Text)`_ - -- requires `doc-utils`_ - -In each case, the filter expects formatted markup as a string and returns a -string representing the marked-up text. For example, the ``textile`` filter -converts text that is marked-up in Textile format to HTML. - -To activate these filters, add ``'django.contrib.markup'`` to your -:setting:`INSTALLED_APPS` setting. Once you've done that, use -``{% load markup %}`` in a template, and you'll have access to these filters. -For more documentation, read the source code in -:file:`django/contrib/markup/templatetags/markup.py`. - -.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29 -.. _Markdown: http://en.wikipedia.org/wiki/Markdown -.. _ReST (ReStructured Text): http://en.wikipedia.org/wiki/ReStructuredText -.. _PyTextile: http://loopcore.com/python-textile/ -.. _Python-markdown: http://www.freewisdom.org/projects/python-markdown -.. _doc-utils: http://docutils.sf.net/ - -ReStructured Text ------------------ - -When using the `restructuredtext` markup filter you can define a :setting:`RESTRUCTUREDTEXT_FORMAT_SETTINGS` -in your django settings to override the default writer settings. See the `restructuredtext writer settings`_ for -details on what these settings are. +A collection of template filters that implement common markup languages -.. _restructuredtext writer settings: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer +See the :doc:`markup documentation </ref/contrib/markup>`. messages ======== @@ -183,21 +151,21 @@ messages A framework for storing and retrieving temporary cookie- or session-based messages -See the :ref:`messages documentation <ref-contrib-messages>`. +See the :doc:`messages documentation </ref/contrib/messages>`. redirects ========= A framework for managing redirects. -See the :ref:`redirects documentation <ref-contrib-redirects>`. +See the :doc:`redirects documentation </ref/contrib/redirects>`. sessions ======== A framework for storing data in anonymous sessions. -See the :ref:`sessions documentation <topics-http-sessions>`. +See the :doc:`sessions documentation </topics/http/sessions>`. sites ===== @@ -206,21 +174,21 @@ A light framework that lets you operate multiple Web sites off of the same database and Django installation. It gives you hooks for associating objects to one or more sites. -See the :ref:`sites documentation <ref-contrib-sites>`. +See the :doc:`sites documentation </ref/contrib/sites>`. sitemaps ======== A framework for generating Google sitemap XML files. -See the :ref:`sitemaps documentation <ref-contrib-sitemaps>`. +See the :doc:`sitemaps documentation </ref/contrib/sitemaps>`. syndication =========== A framework for generating syndication feeds, in RSS and Atom, quite easily. -See the :ref:`syndication documentation <ref-contrib-syndication>`. +See the :doc:`syndication documentation </ref/contrib/syndication>`. webdesign ========= @@ -228,7 +196,7 @@ webdesign Helpers and utilities targeted primarily at Web *designers* rather than Web *developers*. -See the :ref:`Web design helpers documentation <ref-contrib-webdesign>`. +See the :doc:`Web design helpers documentation </ref/contrib/webdesign>`. Other add-ons ============= diff --git a/docs/ref/contrib/localflavor.txt b/docs/ref/contrib/localflavor.txt index 1c58e2d5e8..48cfa6340a 100644 --- a/docs/ref/contrib/localflavor.txt +++ b/docs/ref/contrib/localflavor.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-localflavor: - ========================== The "local flavor" add-ons ========================== @@ -17,7 +15,7 @@ Inside that package, country- or culture-specific code is organized into subpackages, named using `ISO 3166 country codes`_. Most of the ``localflavor`` add-ons are localized form components deriving -from the :ref:`forms <topics-forms-index>` framework -- for example, a +from the :doc:`forms </topics/forms/index>` framework -- for example, a :class:`~django.contrib.localflavor.us.forms.USStateField` that knows how to validate U.S. state abbreviations, and a :class:`~django.contrib.localflavor.fi.forms.FISocialSecurityNumber` that @@ -74,7 +72,7 @@ Countries currently supported by :mod:`~django.contrib.localflavor` are: The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage, containing useful code that is not specific to one particular country or culture. Currently, it defines date, datetime and split datetime input fields based on -those from :ref:`forms <topics-forms-index>`, but with non-US default formats. +those from :doc:`forms </topics/forms/index>`, but with non-US default formats. Here's an example of how to use them:: from django import forms diff --git a/docs/ref/contrib/markup.txt b/docs/ref/contrib/markup.txt new file mode 100644 index 0000000000..f2c43fe25f --- /dev/null +++ b/docs/ref/contrib/markup.txt @@ -0,0 +1,42 @@ +===================== +django.contrib.markup +===================== + +.. module:: django.contrib.markup + :synopsis: A collection of template filters that implement common markup languages. + +Django provides template filters that implement the following markup +languages: + + * ``textile`` -- implements `Textile`_ -- requires `PyTextile`_ + * ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_ + * ``restructuredtext`` -- implements `ReST (ReStructured Text)`_ + -- requires `doc-utils`_ + +In each case, the filter expects formatted markup as a string and +returns a string representing the marked-up text. For example, the +``textile`` filter converts text that is marked-up in Textile format +to HTML. + +To activate these filters, add ``'django.contrib.markup'`` to your +:setting:`INSTALLED_APPS` setting. Once you've done that, use +``{% load markup %}`` in a template, and you'll have access to these filters. +For more documentation, read the source code in +:file:`django/contrib/markup/templatetags/markup.py`. + +.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29 +.. _Markdown: http://en.wikipedia.org/wiki/Markdown +.. _ReST (ReStructured Text): http://en.wikipedia.org/wiki/ReStructuredText +.. _PyTextile: http://loopcore.com/python-textile/ +.. _Python-markdown: http://www.freewisdom.org/projects/python-markdown +.. _doc-utils: http://docutils.sf.net/ + +ReStructured Text +----------------- + +When using the ``restructuredtext`` markup filter you can define a +:setting:`RESTRUCTUREDTEXT_FILTER_SETTINGS` in your django settings to +override the default writer settings. See the `restructuredtext writer +settings`_ for details on what these settings are. + +.. _restructuredtext writer settings: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt index 554e70b1f2..3081f2718d 100644 --- a/docs/ref/contrib/messages.txt +++ b/docs/ref/contrib/messages.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-messages: - ====================== The messages framework ====================== @@ -20,8 +18,8 @@ with a specific ``level`` that determines its priority (e.g., ``info``, Enabling messages ================= -Messages are implemented through a :ref:`middleware <ref-middleware>` -class and corresponding :ref:`context processor <ref-templates-api>`. +Messages are implemented through a :doc:`middleware </ref/middleware>` +class and corresponding :doc:`context processor </ref/templates/api>`. To enable message functionality, do the following: @@ -29,7 +27,7 @@ To enable message functionality, do the following: it contains ``'django.contrib.messages.middleware.MessageMiddleware'``. If you are using a :ref:`storage backend <message-storage-backends>` that - relies on :ref:`sessions <topics-http-sessions>` (the default), + relies on :doc:`sessions </topics/http/sessions>` (the default), ``'django.contrib.sessions.middleware.SessionMiddleware'`` must be enabled and appear before ``MessageMiddleware`` in your :setting:`MIDDLEWARE_CLASSES`. @@ -106,7 +104,7 @@ LegacyFallbackStorage The ``LegacyFallbackStorage`` is a temporary tool to facilitate the transition from the deprecated ``user.message_set`` API and will be removed in Django 1.4 according to Django's standard deprecation policy. For more information, see -the full :ref:`release process documentation <internals-release-process>`. +the full :doc:`release process documentation </internals/release-process>`. In addition to the functionality in the ``FallbackStorage``, it adds a custom, read-only storage class that retrieves messages from the user ``Message`` @@ -300,7 +298,7 @@ example:: messages.info(request, 'Hello world.', fail_silently=True) Internally, Django uses this functionality in the create, update, and delete -:ref:`generic views <topics-generic-views>` so that they work even if the +:doc:`generic views </topics/http/generic-views>` so that they work even if the message framework is disabled. .. note:: @@ -343,7 +341,7 @@ window/tab will have its own browsing context. Settings ======== -A few :ref:`Django settings <ref-settings>` give you control over message +A few :doc:`Django settings </ref/settings>` give you control over message behavior: MESSAGE_LEVEL diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt index 6f9c57c09d..f1a58cb207 100644 --- a/docs/ref/contrib/redirects.txt +++ b/docs/ref/contrib/redirects.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-redirects: - ================= The redirects app ================= @@ -47,8 +45,8 @@ Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can put ``RedirectFallbackMiddleware`` at the end of the list, because it's a last resort. -For more on middleware, read the :ref:`middleware docs -<topics-http-middleware>`. +For more on middleware, read the :doc:`middleware docs +</topics/http/middleware>`. How to add, change and delete redirects ======================================= @@ -65,8 +63,8 @@ Via the Python API .. class:: models.Redirect - Redirects are represented by a standard :ref:`Django model <topics-db-models>`, + Redirects are represented by a standard :doc:`Django model </topics/db/models>`, which lives in `django/contrib/redirects/models.py`_. You can access redirect - objects via the :ref:`Django database API <topics-db-queries>`. + objects via the :doc:`Django database API </topics/db/queries>`. .. _django/contrib/redirects/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models.py diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index a71f19d786..7a66cbe9a9 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-sitemaps: - ===================== The sitemap framework ===================== @@ -23,10 +21,10 @@ site. The Django sitemap framework automates the creation of this XML file by letting you express this information in Python code. -It works much like Django's :ref:`syndication framework -<ref-contrib-syndication>`. To create a sitemap, just write a +It works much like Django's :doc:`syndication framework +</ref/contrib/syndication>`. To create a sitemap, just write a :class:`~django.contrib.sitemaps.Sitemap` class and point to it in your -:ref:`URLconf <topics-http-urls>`. +:doc:`URLconf </topics/http/urls>`. Installation ============ @@ -52,7 +50,7 @@ Initialization ============== To activate sitemap generation on your Django site, add this line to your -:ref:`URLconf <topics-http-urls>`:: +:doc:`URLconf </topics/http/urls>`:: (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps}) @@ -217,8 +215,8 @@ The sitemap framework provides a couple convenience classes for common cases: .. class:: FlatPageSitemap The :class:`django.contrib.sitemaps.FlatPageSitemap` class looks at all - :mod:`flatpages <django.contrib.flatpages>` defined for the current - :setting:`SITE_ID` (see the + publicly visible :mod:`flatpages <django.contrib.flatpages>` + defined for the current :setting:`SITE_ID` (see the :mod:`sites documentation <django.contrib.sites>`) and creates an entry in the sitemap. These entries include only the :attr:`~Sitemap.location` attribute -- not :attr:`~Sitemap.lastmod`, @@ -227,7 +225,7 @@ The sitemap framework provides a couple convenience classes for common cases: .. class:: GenericSitemap The :class:`django.contrib.sitemaps.GenericSitemap` class works with any - :ref:`generic views <ref-generic-views>` you already have. + :doc:`generic views </ref/generic-views>` you already have. To use it, create an instance, passing in the same :data:`info_dict` you pass to the generic views. The only requirement is that the dictionary have a :data:`queryset` entry. It may also have a :data:`date_field` entry that specifies a @@ -240,7 +238,7 @@ The sitemap framework provides a couple convenience classes for common cases: Example ------- -Here's an example of a :ref:`URLconf <topics-http-urls>` using both:: +Here's an example of a :doc:`URLconf </topics/http/urls>` using both:: from django.conf.urls.defaults import * from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index b7cb8d6a58..7ff05a5c82 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-sites: - ===================== The "sites" framework ===================== @@ -104,6 +102,8 @@ like this:: This has the same benefits as described in the last section. +.. _hooking-into-current-site-from-views: + Hooking into the current site from views ---------------------------------------- @@ -260,7 +260,7 @@ The ``CurrentSiteManager`` If :class:`~django.contrib.sites.models.Site` plays a key role in your application, consider using the helpful :class:`~django.contrib.sites.managers.CurrentSiteManager` in your -model(s). It's a model :ref:`manager <topics-db-managers>` that +model(s). It's a model :doc:`manager </topics/db/managers>` that automatically filters its queries to include only objects associated with the current :class:`~django.contrib.sites.models.Site`. @@ -322,7 +322,7 @@ and pass a field name that doesn't exist, Django will raise a :exc:`ValueError`. Finally, note that you'll probably want to keep a normal (non-site-specific) ``Manager`` on your model, even if you use :class:`~django.contrib.sites.managers.CurrentSiteManager`. As -explained in the :ref:`manager documentation <topics-db-managers>`, if +explained in the :doc:`manager documentation </topics/db/managers>`, if you define a manager manually, then Django won't create the automatic ``objects = models.Manager()`` manager for you. Also note that certain parts of Django -- namely, the Django admin site and generic views -- @@ -387,7 +387,7 @@ Here's how Django uses the sites framework: .. versionadded:: 1.0 -Some :ref:`django.contrib <ref-contrib-index>` applications take advantage of +Some :doc:`django.contrib </ref/contrib/index>` applications take advantage of the sites framework but are architected in a way that doesn't *require* the sites framework to be installed in your database. (Some people don't want to, or just aren't *able* to install the extra database table that the sites framework diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index 7b47ef8a4e..a12d646a08 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-syndication: - ============================== The syndication feed framework ============================== @@ -38,8 +36,8 @@ Overview The high-level feed-generating framework is supplied by the :class:`~django.contrib.syndication.views.Feed` class. To create a feed, write a :class:`~django.contrib.syndication.views.Feed` class -and point to an instance of it in your :ref:`URLconf -<topics-http-urls>`. +and point to an instance of it in your :doc:`URLconf +</topics/http/urls>`. Feed classes ------------ @@ -54,7 +52,7 @@ Feed classes subclass :class:`django.contrib.syndication.views.Feed`. They can live anywhere in your codebase. Instances of :class:`~django.contrib.syndication.views.Feed` classes -are views which can be used in your :ref:`URLconf <topics-http-urls>`. +are views which can be used in your :doc:`URLconf </topics/http/urls>`. A simple example ---------------- @@ -80,7 +78,7 @@ latest five news items:: return item.description To connect a URL to this feed, put an instance of the Feed object in -your :ref:`URLconf <topics-http-urls>`. For example:: +your :doc:`URLconf </topics/http/urls>`. For example:: from django.conf.urls.defaults import * from myproject.feeds import LatestEntriesFeed @@ -102,7 +100,7 @@ Note: * :meth:`items()` is, simply, a method that returns a list of objects that should be included in the feed as ``<item>`` elements. Although this example returns ``NewsItem`` objects using Django's - :ref:`object-relational mapper <ref-models-querysets>`, :meth:`items()` + :doc:`object-relational mapper </ref/models/querysets>`, :meth:`items()` doesn't have to return model instances. Although you get a few bits of functionality "for free" by using Django models, :meth:`items()` can return any type of object you want. @@ -123,7 +121,7 @@ into those elements. both. If you want to do any special formatting for either the title or - description, :ref:`Django templates <topics-templates>` can be used + description, :doc:`Django templates </topics/templates>` can be used instead. Their paths can be specified with the ``title_template`` and ``description_template`` attributes on the :class:`~django.contrib.syndication.views.Feed` class. The templates are @@ -167,7 +165,7 @@ police beat in Chicago. It'd be silly to create a separate :class:`~django.contrib.syndication.views.Feed` class for each police beat; that would violate the :ref:`DRY principle <dry>` and would couple data to programming logic. Instead, the syndication framework lets you access the -arguments passed from your :ref:`URLconf <topics-http-urls>` so feeds can output +arguments passed from your :doc:`URLconf </topics/http/urls>` so feeds can output items based on information in the feed's URL. On chicagocrime.org, the police-beat feeds are accessible via URLs like this: @@ -175,7 +173,7 @@ On chicagocrime.org, the police-beat feeds are accessible via URLs like this: * :file:`/beats/613/rss/` -- Returns recent crimes for beat 613. * :file:`/beats/1424/rss/` -- Returns recent crimes for beat 1424. -These can be matched with a :ref:`URLconf <topics-http-urls>` line such as:: +These can be matched with a :doc:`URLconf </topics/http/urls>` line such as:: (r'^beats/(?P<beat_id>\d+)/rss/$', BeatFeed()), diff --git a/docs/ref/contrib/webdesign.txt b/docs/ref/contrib/webdesign.txt index e69ad49232..d355d03565 100644 --- a/docs/ref/contrib/webdesign.txt +++ b/docs/ref/contrib/webdesign.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-webdesign: - ======================== django.contrib.webdesign ======================== @@ -9,13 +7,13 @@ django.contrib.webdesign rather than Web *developers*. The ``django.contrib.webdesign`` package, part of the -:ref:`"django.contrib" add-ons <ref-contrib-index>`, provides various Django +:doc:`"django.contrib" add-ons </ref/contrib/index>`, provides various Django helpers that are particularly useful to Web *designers* (as opposed to developers). At present, the package contains only a single template tag. If you have ideas for Web-designer-friendly functionality in Django, please -:ref:`suggest them <internals-contributing>`. +:doc:`suggest them </internals/contributing>`. Template tags ============= diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 3a7c3eaaca..edb2c026dd 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -1,5 +1,3 @@ -.. _ref-databases: - ========= Databases ========= @@ -18,6 +16,22 @@ documentation or reference manuals. PostgreSQL notes ================ +.. versionchanged:: 1.3 + +Django supports PostgreSQL 8.0 and higher. If you want to use +:ref:`database-level autocommit <postgresql-autocommit-mode>`, a +minimum version of PostgreSQL 8.2 is required. + +.. admonition:: Improvements in recent PostgreSQL versions + + PostgreSQL 8.0 and 8.1 `will soon reach end-of-life`_; there have + also been a number of significant performance improvements added + in recent PostgreSQL versions. Although PostgreSQL 8.0 is the minimum + supported version, you would be well advised to use a more recent + version if at all possible. + +.. _will soon reach end-of-life: http://wiki.postgresql.org/wiki/PostgreSQL_Release_Support_Policy + PostgreSQL 8.2 to 8.2.4 ----------------------- @@ -34,11 +48,13 @@ aggregate with a database backend that falls within the affected release range. Transaction handling --------------------- -:ref:`By default <topics-db-transactions>`, Django starts a transaction when a +:doc:`By default </topics/db/transactions>`, Django starts a transaction when a database connection is first used and commits the result at the end of the request/response handling. The PostgreSQL backends normally operate the same as any other Django backend in this respect. +.. _postgresql-autocommit-mode: + Autocommit mode ~~~~~~~~~~~~~~~ @@ -84,6 +100,7 @@ protection for multi-call operations. Indexes for ``varchar`` and ``text`` columns ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. versionadded:: 1.1.2 When specifying ``db_index=True`` on your model fields, Django typically @@ -247,7 +264,7 @@ table (usually called ``django_session``) and the Connecting to the database -------------------------- -Refer to the :ref:`settings documentation <ref-settings>`. +Refer to the :doc:`settings documentation </ref/settings>`. Connection settings are used in this order: diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 0918f5c1f4..6d0993c7f0 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -1,5 +1,3 @@ -.. _ref-django-admin: - ============================= django-admin.py and manage.py ============================= @@ -104,9 +102,9 @@ compilemessages Before 1.0 this was the "bin/compile-messages.py" command. Compiles .po files created with ``makemessages`` to .mo files for use with -the builtin gettext support. See :ref:`topics-i18n`. +the builtin gettext support. See :doc:`/topics/i18n/index`. -Use the :djadminopt:`--locale`` option to specify the locale to process. +Use the :djadminopt:`--locale` option to specify the locale to process. If not provided, all locales are processed. Example usage:: @@ -119,7 +117,7 @@ createcachetable .. django-admin:: createcachetable Creates a cache table named ``tablename`` for use with the database cache -backend. See :ref:`topics-cache` for more information. +backend. See :doc:`/topics/cache` for more information. .. versionadded:: 1.2 @@ -151,8 +149,8 @@ using the ``--username`` and ``--email`` arguments on the command line. If either of those is not supplied, ``createsuperuser`` will prompt for it when running interactively. -This command is only available if Django's :ref:`authentication system -<topics-auth>` (``django.contrib.auth``) is installed. +This command is only available if Django's :doc:`authentication system +</topics/auth>` (``django.contrib.auth``) is installed. dbshell ------- @@ -210,6 +208,12 @@ records to dump. If you're using a :ref:`custom manager <custom-managers>` as the default manager and it filters some of the available records, not all of the objects will be dumped. +.. versionadded:: 1.3 + +The :djadminopt:`--all` option may be provided to specify that +``dumpdata`` should use Django's base manager, dumping records which +might otherwise be filtered or modified by a custom manager. + .. django-admin-option:: --format <fmt> By default, ``dumpdata`` will format its output in JSON, but you can use the @@ -227,6 +231,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 @@ -268,7 +277,6 @@ prompts. The :djadminopt:`--database` option may be used to specify the database to flush. - inspectdb --------- @@ -524,8 +532,8 @@ runfcgi [options] .. django-admin:: runfcgi Starts a set of FastCGI processes suitable for use with any Web server that -supports the FastCGI protocol. See the :ref:`FastCGI deployment documentation -<howto-deployment-fastcgi>` for details. Requires the Python FastCGI module from +supports the FastCGI protocol. See the :doc:`FastCGI deployment documentation +</howto/deployment/fastcgi>` for details. Requires the Python FastCGI module from `flup`_. .. _flup: http://www.saddi.com/software/flup/ @@ -611,7 +619,7 @@ Serving static files with the development server By default, the development server doesn't serve any static files for your site (such as CSS files, images, things under ``MEDIA_URL`` and so forth). If -you want to configure Django to serve static media, read :ref:`howto-static-files`. +you want to configure Django to serve static media, read :doc:`/howto/static-files`. shell ----- @@ -804,8 +812,6 @@ with an appropriate extension (e.g. ``json`` or ``xml``). See the documentation for ``loaddata`` for details on the specification of fixture data files. ---noinput -~~~~~~~~~ The :djadminopt:`--noinput` option may be provided to suppress all user prompts. @@ -819,7 +825,7 @@ test <app or test identifier> .. django-admin:: test -Runs tests for all installed models. See :ref:`topics-testing` for more +Runs tests for all installed models. See :doc:`/topics/testing` for more information. .. versionadded:: 1.2 @@ -844,7 +850,7 @@ For example, this command:: ...would perform the following steps: - 1. Create a test database, as described in :ref:`topics-testing`. + 1. Create a test database, as described in :doc:`/topics/testing`. 2. Populate the test database with fixture data from the given fixtures. (For more on fixtures, see the documentation for ``loaddata`` above.) 3. Runs the Django development server (as in ``runserver``), pointed at @@ -852,7 +858,7 @@ For example, this command:: This is useful in a number of ways: - * When you're writing :ref:`unit tests <topics-testing>` of how your views + * When you're writing :doc:`unit tests </topics/testing>` of how your views act with certain fixture data, you can use ``testserver`` to interact with the views in a Web browser, manually. @@ -889,6 +895,11 @@ To run on 1.2.3.4:7000 with a ``test`` fixture:: django-admin.py testserver --addrport 1.2.3.4:7000 test +.. versionadded:: 1.3 + +The :djadminopt:`--noinput` option may be provided to suppress all user +prompts. + validate -------- @@ -954,6 +965,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 ============== @@ -1107,4 +1119,4 @@ distribution. It enables tab-completion of ``django-admin.py`` and with ``sql``. -See :ref:`howto-custom-management-commands` for how to add customized actions. +See :doc:`/howto/custom-management-commands` for how to add customized actions. diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt index 1fc9b177d4..4a4384376b 100644 --- a/docs/ref/exceptions.txt +++ b/docs/ref/exceptions.txt @@ -1,5 +1,3 @@ -.. _ref-exceptions: - ================= Django Exceptions ================= diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index 1ea5865ea7..f4ae59f241 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -1,5 +1,3 @@ -.. _ref-files-file: - The ``File`` object =================== @@ -20,14 +18,14 @@ Django's ``File`` has the following attributes and methods: The absolute path to the file's location on a local filesystem. - :ref:`Custom file storage systems <howto-custom-file-storage>` may not store + :doc:`Custom file storage systems </howto/custom-file-storage>` may not store files locally; files stored on these systems will have a ``path`` of ``None``. .. attribute:: File.url The URL where the file can be retrieved. This is often useful in - :ref:`templates <topics-templates>`; for example, a bit of a template for + :doc:`templates </topics/templates>`; for example, a bit of a template for displaying a ``Car`` (see above) might look like: .. code-block:: html+django diff --git a/docs/ref/files/index.txt b/docs/ref/files/index.txt index 1d59d5fa23..171fcc6391 100644 --- a/docs/ref/files/index.txt +++ b/docs/ref/files/index.txt @@ -1,5 +1,3 @@ -.. _ref-files-index: - ============= File handling ============= diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt index c8aafa8626..2b055bb60b 100644 --- a/docs/ref/files/storage.txt +++ b/docs/ref/files/storage.txt @@ -1,5 +1,3 @@ -.. _ref-files-storage: - File storage API ================ diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 0d174ea4af..613d7544a9 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -1,5 +1,3 @@ -.. _ref-forms-api: - ============= The Forms API ============= @@ -11,7 +9,7 @@ The Forms API .. admonition:: About this document This document covers the gritty details of Django's forms API. You should - read the :ref:`introduction to working with forms <topics-forms-index>` + read the :doc:`introduction to working with forms </topics/forms/index>` first. .. _ref-forms-api-bound-unbound: @@ -262,7 +260,7 @@ for each field in the "Built-in ``Field`` classes" section below. You can write code to perform validation for particular form fields (based on their name) or for the form as a whole (considering combinations of various -fields). More information about this is in :ref:`ref-forms-validation`. +fields). More information about this is in :doc:`/ref/forms/validation`. Outputting forms as HTML ------------------------ diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 396e51046e..0dd9095a77 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -1,5 +1,3 @@ -.. _ref-forms-fields: - =========== Form fields =========== @@ -192,7 +190,7 @@ The callable will be evaluated only when the unbound form is displayed, not when .. attribute:: Field.widget The ``widget`` argument lets you specify a ``Widget`` class to use when -rendering this ``Field``. See :ref:`ref-forms-widgets` for more information. +rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information. ``help_text`` ~~~~~~~~~~~~~ @@ -267,7 +265,7 @@ error message keys it uses. The ``validators`` argument lets you provide a list of validation functions for this field. -See the :ref:`validators documentation <ref-validators>` for more information. +See the :doc:`validators documentation </ref/validators>` for more information. ``localize`` ~~~~~~~~~~~~ @@ -516,8 +514,8 @@ given length. * Validates that non-empty file data has been bound to the form. * Error message keys: ``required``, ``invalid``, ``missing``, ``empty`` -To learn more about the ``UploadedFile`` object, see the :ref:`file uploads -documentation <topics-http-file-uploads>`. +To learn more about the ``UploadedFile`` object, see the :doc:`file uploads +documentation </topics/http/file-uploads>`. When you use a ``FileField`` in a form, you must also remember to :ref:`bind the file data to the form <binding-uploaded-files>`. diff --git a/docs/ref/forms/index.txt b/docs/ref/forms/index.txt index e310863c7a..610416a363 100644 --- a/docs/ref/forms/index.txt +++ b/docs/ref/forms/index.txt @@ -1,10 +1,8 @@ -.. _ref-forms-index: - ===== Forms ===== -Detailed form API reference. For introductory material, see :ref:`topics-forms-index`. +Detailed form API reference. For introductory material, see :doc:`/topics/forms/index`. .. toctree:: :maxdepth: 1 diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index 911496c9ae..1c047f246f 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -1,5 +1,3 @@ -.. _ref-forms-validation: - Form and field validation ========================= @@ -180,7 +178,7 @@ Using validators .. versionadded:: 1.2 Django's form (and model) fields support use of simple utility functions and -classes known as validators. These can passed to a field's constructor, via +classes known as validators. These can be passed to a field's constructor, via the field's ``validators`` argument, or defined on the Field class itself with the ``default_validators`` attribute. diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 1fc2bfa85d..05215d4d8e 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -1,12 +1,10 @@ -.. _ref-forms-widgets: - ======= 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 +27,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 +53,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 +67,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 +80,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 +101,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 +126,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 +158,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/generic-views.txt b/docs/ref/generic-views.txt index 574db88a60..a7d67c74e3 100644 --- a/docs/ref/generic-views.txt +++ b/docs/ref/generic-views.txt @@ -1,5 +1,3 @@ -.. _ref-generic-views: - ============= Generic views ============= @@ -9,8 +7,8 @@ again and again. In Django, the most common of these patterns have been abstracted into "generic views" that let you quickly provide common views of an object without actually needing to write any Python code. -A general introduction to generic views can be found in the :ref:`topic guide -<topics-generic-views>`. +A general introduction to generic views can be found in the :doc:`topic guide +</topics/http/generic-views>`. This reference contains details of Django's built-in generic views, along with a list of all keyword arguments that a generic view expects. Remember that @@ -18,7 +16,7 @@ arguments may either come from the URL pattern or from the ``extra_context`` additional-information dictionary. Most generic views require the ``queryset`` key, which is a ``QuerySet`` -instance; see :ref:`topics-db-queries` for more information about ``QuerySet`` +instance; see :doc:`/topics/db/queries` for more information about ``QuerySet`` objects. "Simple" generic views @@ -90,9 +88,15 @@ If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410). redirect will use status code 301. If ``False``, then the redirect will use status code 302. By default, ``permanent`` is ``True``. + * ``query_string``: Whether to pass along the GET query string to + the new location. If ``True``, then the query string is appended + to the URL. If ``False``, then the query string is discarded. By + default, ``query_string`` is ``False``. + .. versionadded:: 1.1 The ``permanent`` keyword argument is new in Django 1.1. + **Example:** This example issues a permanent redirect (HTTP status code 301) from @@ -766,8 +770,8 @@ specify the page number in the URL in one of two ways: These values and lists are 1-based, not 0-based, so the first page would be represented as page ``1``. -For more on pagination, read the :ref:`pagination documentation -<topics-pagination>`. +For more on pagination, read the :doc:`pagination documentation +</topics/pagination>`. .. versionadded:: 1.0 @@ -858,8 +862,8 @@ for creating, editing and deleting objects. .. versionchanged:: 1.0 ``django.views.generic.create_update.create_object`` and -``django.views.generic.create_update.update_object`` now use the new :ref:`forms -library <topics-forms-index>` to build and display the form. +``django.views.generic.create_update.update_object`` now use the new :doc:`forms +library </topics/forms/index>` to build and display the form. ``django.views.generic.create_update.create_object`` ---------------------------------------------------- @@ -875,7 +879,7 @@ validation errors (if there are any) and saving the object. If you provide ``form_class``, it should be a ``django.forms.ModelForm`` subclass. Use this argument when you need to customize the model's form. - See the :ref:`ModelForm docs <topics-forms-modelforms>` for more + See the :doc:`ModelForm docs </topics/forms/modelforms>` for more information. Otherwise, ``model`` should be a Django model class and the form used @@ -892,7 +896,7 @@ validation errors (if there are any) and saving the object. * ``login_required``: A boolean that designates whether a user must be logged in, in order to see the page and save changes. This hooks into the - Django :ref:`authentication system <topics-auth>`. By default, this is + Django :doc:`authentication system </topics/auth>`. By default, this is ``False``. If this is ``True``, and a non-logged-in user attempts to visit this page @@ -932,7 +936,7 @@ In addition to ``extra_context``, the template's context will be: <p>{{ form.address.label_tag }} {{ form.address }}</p> </form> - See the :ref:`forms documentation <topics-forms-index>` for more + See the :doc:`forms documentation </topics/forms/index>` for more information about using ``Form`` objects in templates. ``django.views.generic.create_update.update_object`` @@ -951,7 +955,7 @@ model class. If you provide ``form_class``, it should be a ``django.forms.ModelForm`` subclass. Use this argument when you need to customize the model's form. - See the :ref:`ModelForm docs <topics-forms-modelforms>` for more + See the :doc:`ModelForm docs </topics/forms/modelforms>` for more information. Otherwise, ``model`` should be a Django model class and the form used @@ -977,7 +981,7 @@ model class. * ``login_required``: A boolean that designates whether a user must be logged in, in order to see the page and save changes. This hooks into the - Django :ref:`authentication system <topics-auth>`. By default, this is + Django :doc:`authentication system </topics/auth>`. By default, this is ``False``. If this is ``True``, and a non-logged-in user attempts to visit this page @@ -1020,7 +1024,7 @@ In addition to ``extra_context``, the template's context will be: <p>{{ form.address.label_tag }} {{ form.address }}</p> </form> - See the :ref:`forms documentation <topics-forms-index>` for more + See the :doc:`forms documentation </topics/forms/index>` for more information about using ``Form`` objects in templates. * ``object``: The original object being edited. This variable's name @@ -1059,7 +1063,7 @@ contain a form that POSTs to the same URL. * ``login_required``: A boolean that designates whether a user must be logged in, in order to see the page and save changes. This hooks into the - Django :ref:`authentication system <topics-auth>`. By default, this is + Django :doc:`authentication system </topics/auth>`. By default, this is ``False``. If this is ``True``, and a non-logged-in user attempts to visit this page diff --git a/docs/ref/index.txt b/docs/ref/index.txt index a2088ed6ce..09194178af 100644 --- a/docs/ref/index.txt +++ b/docs/ref/index.txt @@ -1,5 +1,3 @@ -.. _ref-index: - ============= API Reference ============= diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index 2afd79038f..290ea2736d 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -1,5 +1,3 @@ -.. _ref-middleware: - ========== Middleware ========== @@ -9,7 +7,7 @@ Middleware This document explains all middleware components that come with Django. For information on how how to use them and how to write your own middleware, see -the :ref:`middleware usage guide <topics-http-middleware>`. +the :doc:`middleware usage guide </topics/http/middleware>`. Available middleware ==================== @@ -26,7 +24,7 @@ Cache middleware Enable the site-wide cache. If these are enabled, each Django-powered page will be cached for as long as the :setting:`CACHE_MIDDLEWARE_SECONDS` setting -defines. See the :ref:`cache documentation <topics-cache>`. +defines. See the :doc:`cache documentation </topics/cache>`. "Common" middleware ------------------- @@ -136,8 +134,8 @@ Locale middleware .. class:: django.middleware.locale.LocaleMiddleware Enables language selection based on data from the request. It customizes -content for each user. See the :ref:`internationalization documentation -<topics-i18n>`. +content for each user. See the :doc:`internationalization documentation +</topics/i18n/index>`. Message middleware ------------------ @@ -151,7 +149,7 @@ Message middleware ``MessageMiddleware`` was added. Enables cookie- and session-based message support. See the -:ref:`messages documentation <ref-contrib-messages>`. +:doc:`messages documentation </ref/contrib/messages>`. Session middleware ------------------ @@ -161,8 +159,8 @@ Session middleware .. class:: django.contrib.sessions.middleware.SessionMiddleware -Enables session support. See the :ref:`session documentation -<topics-http-sessions>`. +Enables session support. See the :doc:`session documentation +</topics/http/sessions>`. Authentication middleware ------------------------- @@ -173,8 +171,8 @@ Authentication middleware .. class:: django.contrib.auth.middleware.AuthenticationMiddleware Adds the ``user`` attribute, representing the currently-logged-in user, to -every incoming ``HttpRequest`` object. See :ref:`Authentication in Web requests -<topics-auth>`. +every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests +</topics/auth>`. CSRF protection middleware -------------------------- @@ -189,7 +187,7 @@ CSRF protection middleware Adds protection against Cross Site Request Forgeries by adding hidden form fields to POST forms and checking requests for the correct value. See the -:ref:`Cross Site Request Forgery protection documentation <ref-contrib-csrf>`. +:doc:`Cross Site Request Forgery protection documentation </ref/contrib/csrf>`. Transaction middleware ---------------------- @@ -208,4 +206,4 @@ running outside of it run with commit-on-save - the default Django behavior. Middleware modules running inside it (coming later in the stack) will be under the same transaction control as the view functions. -See the :ref:`transaction management documentation <topics-db-transactions>`. +See the :doc:`transaction management documentation </topics/db/transactions>`. diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 3a0066987f..68208b3bfe 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -1,5 +1,3 @@ -.. _ref-models-fields: - ===================== Model field reference ===================== @@ -14,8 +12,8 @@ This document contains all the gory details about all the `field options`_ and .. seealso:: - If the built-in fields don't do the trick, you can easily :ref:`write your - own custom model fields <howto-custom-model-fields>`. + If the built-in fields don't do the trick, you can easily :doc:`write your + own custom model fields </howto/custom-model-fields>`. .. note:: @@ -293,8 +291,6 @@ A human-readable name for the field. If the verbose name isn't given, Django will automatically create it using the field's attribute name, converting underscores to spaces. See :ref:`Verbose field names <verbose-field-names>`. -.. _model-field-types: - ``validators`` ------------------- @@ -302,9 +298,10 @@ underscores to spaces. See :ref:`Verbose field names <verbose-field-names>`. .. attribute:: Field.validators -A list of validators to run for this field.See the :ref:`validators -documentation <ref-validators>` for more information. +A list of validators to run for this field.See the :doc:`validators +documentation </ref/validators>` for more information. +.. _model-field-types: Field types =========== @@ -370,8 +367,8 @@ The admin represents this as an ``<input type="text">`` (a single-line input). If you are writing an application that must be portable to multiple database backends, you should be aware that there are restrictions on - ``max_length`` for some backends. Refer to the :ref:`database backend - notes <ref-databases>` for details. + ``max_length`` for some backends. Refer to the :doc:`database backend + notes </ref/databases>` for details. .. admonition:: MySQL users @@ -518,7 +515,7 @@ Also has one optional argument: .. versionadded:: 1.0 Optional. A storage object, which handles the storage and retrieval of your - files. See :ref:`topics-files` for details on how to provide this object. + files. See :doc:`/topics/files` for details on how to provide this object. The admin represents this field as an ``<input type="file">`` (a file-upload widget). @@ -553,7 +550,7 @@ day. If you upload a file on Jan. 15, 2007, it will be saved in the directory If you want to retrieve the upload file's on-disk filename, or a URL that refers to that file, or the file's size, you can use the :attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url` -and :attr:`~django.core.files.File.size` attributes; see :ref:`topics-files`. +and :attr:`~django.core.files.File.size` attributes; see :doc:`/topics/files`. Note that whenever you deal with uploaded files, you should pay close attention to where you're uploading them and what type of files they are, to avoid @@ -903,7 +900,7 @@ define the details of how the relation works. .. attribute:: ForeignKey.limit_choices_to - A dictionary of lookup arguments and values (see :ref:`topics-db-queries`) + A dictionary of lookup arguments and values (see :doc:`/topics/db/queries`) that limit the available admin choices for this object. Use this with functions from the Python ``datetime`` module to limit choices of objects by date. For example:: diff --git a/docs/ref/models/index.txt b/docs/ref/models/index.txt index 64b47b26cc..b5896c35ed 100644 --- a/docs/ref/models/index.txt +++ b/docs/ref/models/index.txt @@ -1,10 +1,8 @@ -.. _ref-models-index: - ====== Models ====== -Model API reference. For introductory material, see :ref:`topics-db-models`. +Model API reference. For introductory material, see :doc:`/topics/db/models`. .. toctree:: :maxdepth: 1 diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 7e6cdeb5c7..dfe4c747e8 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -1,5 +1,3 @@ -.. _ref-models-instances: - ======================== Model instance reference ======================== @@ -7,13 +5,13 @@ Model instance reference .. currentmodule:: django.db.models This document describes the details of the ``Model`` API. It builds on the -material presented in the :ref:`model <topics-db-models>` and :ref:`database -query <topics-db-queries>` guides, so you'll probably want to read and +material presented in the :doc:`model </topics/db/models>` and :doc:`database +query </topics/db/queries>` guides, so you'll probably want to read and understand those documents before reading this one. Throughout this reference we'll use the :ref:`example weblog models -<queryset-model-example>` presented in the :ref:`database query guide -<topics-db-queries>`. +<queryset-model-example>` presented in the :doc:`database query guide +</topics/db/queries>`. Creating objects ================ @@ -45,8 +43,8 @@ All three steps are performed when you call by a model's When you use a ``ModelForm``, the call to ``is_valid()`` will perform these validation steps for all the fields that are included on the -form. (See the :ref:`ModelForm documentation -<topics-forms-modelforms>` for more information.) You should only need +form. (See the :doc:`ModelForm documentation +</topics/forms/modelforms>` for more information.) You should only need to call a model's ``full_clean()`` method if you plan to handle validation errors yourself, or if you have excluded fields from the ModelForm that require validation. @@ -107,9 +105,9 @@ 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(): + article.full_clean() except ValidationError, e: non_field_errors = e.message_dict[NON_FIELD_ERRORS] @@ -215,7 +213,7 @@ What happens when you save? When you save an object, Django performs the following steps: - 1. **Emit a pre-save signal.** The :ref:`signal <ref-signals>` + 1. **Emit a pre-save signal.** The :doc:`signal </ref/signals>` :attr:`django.db.models.signals.pre_save` is sent, allowing any functions listening for that signal to take some customized action. @@ -426,8 +424,8 @@ Django uses this in its admin interface. If an object defines link that will jump you directly to the object's public view, according to ``get_absolute_url()``. -Also, a couple of other bits of Django, such as the :ref:`syndication feed -framework <ref-contrib-syndication>`, use ``get_absolute_url()`` as a +Also, a couple of other bits of Django, such as the :doc:`syndication feed +framework </ref/contrib/syndication>`, use ``get_absolute_url()`` as a convenience to reward people who've defined the method. It's good practice to use ``get_absolute_url()`` in templates, instead of @@ -517,14 +515,14 @@ the ``url`` function):: ...and then using that name to perform the reverse URL resolution instead of the view name:: - from django.db.models import permalink + from django.db import models @models.permalink def get_absolute_url(self): return ('people_view', [str(self.id)]) -More details on named URL patterns are in the :ref:`URL dispatch documentation -<topics-http-urls>`. +More details on named URL patterns are in the :doc:`URL dispatch documentation +</topics/http/urls>`. Extra instance methods ====================== @@ -570,3 +568,5 @@ described in :ref:`Field lookups <field-lookups>`. Note that in the case of identical date values, these methods will use the ID as a fallback check. This guarantees that no records are skipped or duplicated. + +That also means you cannot use those methods on unsaved objects. diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index f3e7363e36..3dfcdfffbc 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -1,5 +1,3 @@ -.. _ref-models-options: - ====================== Model ``Meta`` options ====================== diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 56ff6444e4..87680d3e4d 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1,5 +1,3 @@ -.. _ref-models-querysets: - ====================== QuerySet API reference ====================== @@ -7,13 +5,13 @@ QuerySet API reference .. currentmodule:: django.db.models.QuerySet This document describes the details of the ``QuerySet`` API. It builds on the -material presented in the :ref:`model <topics-db-models>` and :ref:`database -query <topics-db-queries>` guides, so you'll probably want to read and +material presented in the :doc:`model </topics/db/models>` and :doc:`database +query </topics/db/queries>` guides, so you'll probably want to read and understand those documents before reading this one. Throughout this reference we'll use the :ref:`example weblog models -<queryset-model-example>` presented in the :ref:`database query guide -<topics-db-queries>`. +<queryset-model-example>` presented in the :doc:`database query guide +</topics/db/queries>`. .. _when-querysets-are-evaluated: @@ -223,8 +221,8 @@ control the name of the annotation:: >>> q[0].number_of_entries 42 -For an in-depth discussion of aggregation, see :ref:`the topic guide on -Aggregation <topics-db-aggregation>`. +For an in-depth discussion of aggregation, see :doc:`the topic guide on +Aggregation </topics/db/aggregation>`. ``order_by(*fields)`` ~~~~~~~~~~~~~~~~~~~~~ @@ -332,8 +330,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 +363,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 +672,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)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -712,9 +703,10 @@ of the arguments is required, but you should use at least one of them. greater than Jan. 1, 2006. Django inserts the given SQL snippet directly into the ``SELECT`` - statement, so the resulting SQL of the above example would be:: + statement, so the resulting SQL of the above example would be something + like:: - SELECT blog_entry.*, (pub_date > '2006-01-01') + SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent FROM blog_entry; @@ -843,8 +835,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)`` ~~~~~~~~~~~~~~~~~~ @@ -870,7 +860,7 @@ deferred field will be retrieved from the database if you access that field You can make multiple calls to ``defer()``. Each call adds new fields to the deferred set:: - # Defers both the body and lede fields. + # Defers both the body and headline fields. Entry.objects.defer("body").filter(rating=5).defer("headline") The order in which fields are added to the deferred set does not matter. Calling ``defer()`` with a field name that has already been deferred is harmless (the field will still be deferred). @@ -930,7 +920,7 @@ immediately; the remainder are deferred. Thus, successive calls to ``only()`` result in only the final fields being considered:: # This will defer all fields except the headline. - Entry.objects.only("body", "lede").only("headline") + Entry.objects.only("body", "rating").only("headline") Since ``defer()`` acts incrementally (adding fields to the deferred list), you can combine calls to ``only()`` and ``defer()`` and things will behave @@ -973,8 +963,6 @@ something *other than* a ``QuerySet``. These methods do not use a cache (see :ref:`caching-and-querysets`). Rather, they query the database each time they're called. -.. _get-kwargs: - ``get(**kwargs)`` ~~~~~~~~~~~~~~~~~ @@ -1143,8 +1131,6 @@ Example:: If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary. -.. _queryset-iterator: - ``iterator()`` ~~~~~~~~~~~~~~ @@ -1216,8 +1202,8 @@ control the name of the aggregation value that is returned:: >>> q = Blog.objects.aggregate(number_of_entries=Count('entry')) {'number_of_entries': 16} -For an in-depth discussion of aggregation, see :ref:`the topic guide on -Aggregation <topics-db-aggregation>`. +For an in-depth discussion of aggregation, see :doc:`the topic guide on +Aggregation </topics/db/aggregation>`. ``exists()`` ~~~~~~~~~~~~ @@ -1277,7 +1263,7 @@ SQL equivalents:: a Django setting. It's possible to configure your MySQL tables to use case-sensitive comparisons, but some trade-offs are involved. For more information about this, see the :ref:`collation section <mysql-collation>` - in the :ref:`databases <ref-databases>` documentation. + in the :doc:`databases </ref/databases>` documentation. .. fieldlookup:: iexact @@ -1570,7 +1556,7 @@ Example:: SQL equivalent:: - SELECT ... WHERE EXTRACT('year' FROM pub_date) = '2005'; + SELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31 23:59:59.999999'; (The exact SQL syntax varies for each database engine.) @@ -1736,7 +1722,7 @@ Aggregation Functions Django provides the following aggregation functions in the ``django.db.models`` module. For details on how to use these aggregate functions, see -:ref:`the topic guide on aggregation <topics-db-aggregation>`. +:doc:`the topic guide on aggregation </topics/db/aggregation>`. ``Avg`` ~~~~~~~ diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index f58cfe7301..0481644d7a 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -1,5 +1,3 @@ -.. _ref-models-relations: - ========================= Related objects reference ========================= diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index fa8baf0783..b8b08829e9 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -1,5 +1,3 @@ -.. _ref-request-response: - ============================ Request and response objects ============================ @@ -32,10 +30,25 @@ All attributes except ``session`` should be considered read-only. .. attribute:: HttpRequest.path - A string representing the full path to the requested page, not including - the domain. + A string representing the full path to the requested page, not including + the domain. + + Example: ``"/music/bands/the_beatles/"`` + +.. attribute:: HttpRequest.path_info + + Under some web server configurations, the portion of the URL after the host + name is split up into a script prefix portion and a path info portion + (this happens, for example, when using the ``django.root`` option + with the :ref:`modpython handler from Apache <howto-deployment-modpython>`). + The ``path_info`` attribute always contains the path info portion of the + path, no matter what web server is being used. Using this instead of + attr:`~HttpRequest.path` can make your code much easier to move between test + and deployment servers. - Example: ``"/music/bands/the_beatles/"`` + For example, if the ``django.root`` for your application is set to + ``"/minfo"``, then ``path`` might be ``"/minfo/music/bands/the_beatles/"`` + and ``path_info`` would be ``"/music/bands/the_beatles/"``. .. attribute:: HttpRequest.method @@ -106,7 +119,7 @@ All attributes except ``session`` should be considered read-only. * ``chunks(chunk_size=None)`` -- A generator that yields sequential chunks of data. - See :ref:`topics-files` for more information. + See :doc:`/topics/files` for more information. Note that ``FILES`` will only contain data if the request method was POST and the ``<form>`` that posted to the request had @@ -165,14 +178,14 @@ All attributes except ``session`` should be considered read-only. ``user`` is only available if your Django installation has the ``AuthenticationMiddleware`` activated. For more, see - :ref:`topics-auth`. + :doc:`/topics/auth`. .. attribute:: HttpRequest.session A readable-and-writable, dictionary-like object that represents the current session. This is only available if your Django installation has session - support activated. See the :ref:`session documentation - <topics-http-sessions>` for full details. + support activated. See the :doc:`session documentation + </topics/http/sessions>` for full details. .. attribute:: HttpRequest.raw_post_data @@ -286,7 +299,7 @@ a subclass of dictionary. Exceptions are outlined here: .. method:: QueryDict.setdefault(key, default) Just like the standard dictionary ``setdefault()`` method, except it uses - ``__setitem__`` internally. + ``__setitem__()`` internally. .. method:: QueryDict.update(other_dict) @@ -305,7 +318,7 @@ a subclass of dictionary. Exceptions are outlined here: .. method:: QueryDict.items() Just like the standard dictionary ``items()`` method, except this uses the - same last-value logic as ``__getitem()__``. For example:: + same last-value logic as ``__getitem__()``. For example:: >>> q = QueryDict('a=1&a=2&a=3') >>> q.items() @@ -315,7 +328,7 @@ a subclass of dictionary. Exceptions are outlined here: Just like the standard dictionary ``iteritems()`` method. Like :meth:`QueryDict.items()` this uses the same last-value logic as - :meth:`QueryDict.__getitem()__`. + :meth:`QueryDict.__getitem__()`. .. method:: QueryDict.iterlists() @@ -325,7 +338,7 @@ a subclass of dictionary. Exceptions are outlined here: .. method:: QueryDict.values() Just like the standard dictionary ``values()`` method, except this uses the - same last-value logic as ``__getitem()__``. For example:: + same last-value logic as ``__getitem__()``. For example:: >>> q = QueryDict('a=1&a=2&a=3') >>> q.values() @@ -498,11 +511,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) @@ -516,8 +529,11 @@ Methods * ``max_age`` should be a number of seconds, or ``None`` (default) if the cookie should last only as long as the client's browser session. - * ``expires`` should be a string in the format - ``"Wdy, DD-Mon-YY HH:MM:SS GMT"``. + If ``expires`` is not specified, it will be calculated. + * ``expires`` should either be a string in the format + ``"Wdy, DD-Mon-YY HH:MM:SS GMT"`` or a ``datetime.datetime`` object + in UTC. If ``expires`` is a ``datetime`` object, the ``max_age`` + will be calculated. * Use ``domain`` if you want to set a cross-domain cookie. For example, ``domain=".lawrence.com"`` will set a cookie that is readable by the domains www.lawrence.com, blogs.lawrence.com and diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 58f87b9cf4..b5556deac8 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -1,5 +1,3 @@ -.. _ref-settings: - ======== Settings ======== @@ -74,7 +72,7 @@ of (Full name, e-mail address). Example:: (('John', 'john@example.com'), ('Mary', 'mary@example.com')) Note that Django will e-mail *all* of these people whenever an error happens. -See :ref:`howto-error-reporting` for more information. +See :doc:`/howto/error-reporting` for more information. .. setting:: ALLOWED_INCLUDE_ROOTS @@ -99,7 +97,7 @@ APPEND_SLASH Default: ``True`` Whether to append trailing slashes to URLs. This is only used if -``CommonMiddleware`` is installed (see :ref:`topics-http-middleware`). See also +``CommonMiddleware`` is installed (see :doc:`/topics/http/middleware`). See also ``PREPEND_WWW``. .. setting:: AUTHENTICATION_BACKENDS @@ -110,8 +108,8 @@ AUTHENTICATION_BACKENDS Default: ``('django.contrib.auth.backends.ModelBackend',)`` A tuple of authentication backend classes (as strings) to use when attempting to -authenticate a user. See the :ref:`authentication backends documentation -<authentication-backends>` for details. +authenticate a user. See the :doc:`authentication backends documentation +</ref/authbackends>` for details. .. setting:: AUTH_PROFILE_MODULE @@ -130,7 +128,23 @@ CACHE_BACKEND Default: ``'locmem://'`` -The cache backend to use. See :ref:`topics-cache`. +The cache backend to use. See :doc:`/topics/cache`. + +.. setting:: CACHE_MIDDLEWARE_ANONYMOUS_ONLY + +CACHE_MIDDLEWARE_ANONYMOUS_ONLY +------------------------------- + +Default: ``False`` + +If the value of this setting is ``True``, only anonymous requests (i.e., not +those made by a logged-in user) will be cached. Otherwise, the middleware +caches every page that doesn't have GET or POST parameters. + +If you set the value of this setting to ``True``, you should make sure you've +activated ``AuthenticationMiddleware``. + +See the :doc:`cache documentation </topics/cache>` for more information. .. setting:: CACHE_MIDDLEWARE_KEY_PREFIX @@ -140,7 +154,7 @@ CACHE_MIDDLEWARE_KEY_PREFIX Default: ``''`` (Empty string) The cache key prefix that the cache middleware should use. See -:ref:`topics-cache`. +:doc:`/topics/cache`. .. setting:: CACHE_MIDDLEWARE_SECONDS @@ -152,18 +166,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 +181,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 :doc:`/ref/contrib/csrf`. + .. setting:: CSRF_FAILURE_VIEW CSRF_FAILURE_VIEW @@ -195,7 +209,7 @@ is rejected by the CSRF protection. The function should have this signature:: where ``reason`` is a short message (intended for developers or logging, not for end users) indicating the reason the request was rejected. See -:ref:`ref-contrib-csrf`. +:doc:`/ref/contrib/csrf`. .. setting:: DATABASES @@ -208,7 +222,7 @@ DATABASES Default: ``{}`` (Empty dictionary) A dictionary containing the settings for all databases to be used with -Django. It is a nested dictionary who's contents maps database aliases +Django. It is a nested dictionary whose contents maps database aliases to a dictionary containing the options for an individual database. The :setting:`DATABASES` setting must configure a ``default`` database; @@ -385,8 +399,19 @@ If the default value (``None``) is used with the SQLite database engine, the tests will use a memory resident database. For all other database engines the test database will use the name ``'test_' + DATABASE_NAME``. -See :ref:`topics-testing`. +See :doc:`/topics/testing`. +.. setting:: TEST_USER + +TEST_USER +~~~~~~~~~ + +Default: ``None`` + +This is an Oracle-specific setting. + +The username to use when connecting to the Oracle database that will be used +when running tests. .. setting:: DATABASE_ROUTERS @@ -441,7 +466,7 @@ to be displayed. See also ``DATETIME_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``. -.. _datetime: http://docs.python.org/library/datetime.html#strftime-behavior +.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior .. setting:: DATETIME_FORMAT @@ -481,7 +506,7 @@ to be displayed. See also ``DATE_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``. -.. _datetime: http://docs.python.org/library/datetime.html#strftime-behavior +.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior .. setting:: DEBUG @@ -494,8 +519,9 @@ A boolean that turns on/off debug mode. If you define custom settings, `django/views/debug.py`_ has a ``HIDDEN_SETTINGS`` regular expression which will hide from the DEBUG view anything that contains -``'SECRET'``, ``'PASSWORD'``, or ``'PROFANITIES'``. This allows untrusted users to -be able to give backtraces without seeing sensitive (or offensive) settings. +``'SECRET'``, ``'PASSWORD'``, ``'PROFANITIES'``, or ``'SIGNATURE'``. This allows +untrusted users to be able to give backtraces without seeing sensitive (or +offensive) settings. Still, note that there are always going to be sections of your debug output that are inappropriate for public consumption. File paths, configuration options, and @@ -554,7 +580,7 @@ Default content type to use for all ``HttpResponse`` objects, if a MIME type isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the ``Content-Type`` header. -.. setting:: DEFAULT_FROM_EMAIL +.. setting:: DEFAULT_FILE_STORAGE DEFAULT_FILE_STORAGE -------------------- @@ -562,7 +588,9 @@ DEFAULT_FILE_STORAGE Default: ``'django.core.files.storage.FileSystemStorage'`` Default file storage class to be used for any file-related operations that don't -specify a particular storage system. See :ref:`topics-files`. +specify a particular storage system. See :doc:`/topics/files`. + +.. setting:: DEFAULT_FROM_EMAIL DEFAULT_FROM_EMAIL ------------------ @@ -572,29 +600,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 @@ -606,7 +634,7 @@ Default: ``()`` (Empty tuple) List of compiled regular expression objects representing User-Agent strings that are not allowed to visit any page, systemwide. Use this for bad robots/crawlers. This is only used if ``CommonMiddleware`` is installed (see -:ref:`topics-http-middleware`). +:doc:`/topics/http/middleware`). .. setting:: EMAIL_BACKEND @@ -615,10 +643,10 @@ EMAIL_BACKEND .. versionadded:: 1.2 -Default: ``'django.core.mail.backends.smtp'`` +Default: ``'django.core.mail.backends.smtp.EmailBackend'`` The backend to use for sending emails. For the list of available backends see -:ref:`topics-email`. +:doc:`/topics/email`. .. setting:: EMAIL_FILE_PATH @@ -723,7 +751,7 @@ Default:: ("django.core.files.uploadhandler.MemoryFileUploadHandler", "django.core.files.uploadhandler.TemporaryFileUploadHandler",) -A tuple of handlers to use for uploading. See :ref:`topics-files` for details. +A tuple of handlers to use for uploading. See :doc:`/topics/files` for details. .. setting:: FILE_UPLOAD_MAX_MEMORY_SIZE @@ -735,22 +763,7 @@ FILE_UPLOAD_MAX_MEMORY_SIZE 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. +the file system. See :doc:`/topics/files` for details. .. setting:: FILE_UPLOAD_PERMISSIONS @@ -780,6 +793,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 :doc:`/topics/files` for details. + .. setting:: FIRST_DAY_OF_WEEK FIRST_DAY_OF_WEEK @@ -806,7 +834,7 @@ Default: ``()`` (Empty tuple) List of locations of the fixture data files, in search order. Note that these paths should use Unix-style forward slashes, even on Windows. See -:ref:`topics-testing`. +:doc:`/topics/testing`. FORCE_SCRIPT_NAME ------------------ @@ -866,7 +894,7 @@ Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')`` A tuple of strings that specify beginnings of URLs that should be ignored by the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and -the :ref:`howto-error-reporting`. +the :doc:`/howto/error-reporting`. .. setting:: INSTALLED_APPS @@ -899,7 +927,7 @@ A tuple of IP addresses, as strings, that: * See debug comments, when ``DEBUG`` is ``True`` * Receive X headers if the ``XViewMiddleware`` is installed (see - :ref:`topics-http-middleware`) + :doc:`/topics/http/middleware`) .. setting:: LANGUAGE_CODE @@ -910,7 +938,7 @@ Default: ``'en-us'`` A string representing the language code for this installation. This should be in standard :term:`language format<language code>`. For example, U.S. English is -``"en-us"``. See :ref:`topics-i18n`. +``"en-us"``. See :doc:`/topics/i18n/index`. .. setting:: LANGUAGE_COOKIE_NAME @@ -923,7 +951,7 @@ Default: ``'django_language'`` The name of the cookie to use for the language cookie. This can be whatever you want (but should be different from ``SESSION_COOKIE_NAME``). See -:ref:`topics-i18n`. +:doc:`/topics/i18n/index`. .. setting:: LANGUAGES @@ -941,7 +969,7 @@ The list is a tuple of two-tuples in the format ``(language code, language name)``, the ``language code`` part should be a :term:`language name<language code>` -- for example, ``('ja', 'Japanese')``. This specifies which languages are available for language selection. See -:ref:`topics-i18n`. +:doc:`/topics/i18n/index`. Generally, the default value should suffice. Only set this setting if you want to restrict language selection to a subset of the Django-provided languages. @@ -1061,7 +1089,7 @@ MESSAGE_LEVEL Default: `messages.INFO` Sets the minimum message level that will be recorded by the messages -framework. See the :ref:`messages documentation <ref-contrib-messages>` for +framework. See the :doc:`messages documentation </ref/contrib/messages>` for more details. MESSAGE_STORAGE @@ -1072,7 +1100,7 @@ MESSAGE_STORAGE Default: ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'`` Controls where Django stores message data. See the -:ref:`messages documentation <ref-contrib-messages>` for more details. +:doc:`messages documentation </ref/contrib/messages>` for more details. MESSAGE_TAGS ------------ @@ -1088,7 +1116,7 @@ Default:: messages.ERROR: 'error',} Sets the mapping of message levels to message tags. See the -:ref:`messages documentation <ref-contrib-messages>` for more details. +:doc:`messages documentation </ref/contrib/messages>` for more details. MIDDLEWARE_CLASSES ------------------ @@ -1101,12 +1129,12 @@ Default:: 'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.messages.middleware.MessageMiddleware',) -A tuple of middleware classes to use. See :ref:`topics-http-middleware`. +A tuple of middleware classes to use. See :doc:`/topics/http/middleware`. .. versionchanged:: 1.2 ``'django.contrib.messages.middleware.MessageMiddleware'`` was added to the - default. For more information, see the :ref:`messages documentation - <ref-contrib-messages>`. + default. For more information, see the :doc:`messages documentation + </ref/contrib/messages>`. .. setting:: MONTH_DAY_FORMAT @@ -1152,7 +1180,7 @@ PREPEND_WWW Default: ``False`` Whether to prepend the "www." subdomain to URLs that don't have it. This is only -used if ``CommonMiddleware`` is installed (see :ref:`topics-http-middleware`). +used if ``CommonMiddleware`` is installed (see :doc:`/topics/http/middleware`). See also ``APPEND_SLASH``. .. setting:: PROFANITIES_LIST @@ -1167,6 +1195,21 @@ We don't list the default values here, because that would be profane. To see the default values, see the file `django/conf/global_settings.py`_. .. _django/conf/global_settings.py: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py + +.. setting:: RESTRUCTUREDTEXT_FILTER_SETTINGS + +RESTRUCTUREDTEXT_FILTER_SETTINGS +-------------------------------- + +Default: ``{}`` + +A dictionary containing settings for the ``restructuredtext`` markup filter from +the :doc:`django.contrib.markup application </ref/contrib/markup>`. They override +the default writer settings. See the Docutils restructuredtext `writer settings +docs`_ for details. + +.. _writer settings docs: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer + .. setting:: ROOT_URLCONF ROOT_URLCONF @@ -1200,8 +1243,8 @@ Default: ``False`` Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a Django-powered page that is 404ed with a non-empty referer (i.e., a broken link). This is only used if ``CommonMiddleware`` is installed (see -:ref:`topics-http-middleware`. See also ``IGNORABLE_404_STARTS``, -``IGNORABLE_404_ENDS`` and :ref:`howto-error-reporting`. +:doc:`/topics/http/middleware`. See also ``IGNORABLE_404_STARTS``, +``IGNORABLE_404_ENDS`` and :doc:`/howto/error-reporting`. .. setting:: SERIALIZATION_MODULES @@ -1226,27 +1269,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 @@ -1254,7 +1276,7 @@ SESSION_COOKIE_AGE Default: ``1209600`` (2 weeks, in seconds) -The age of session cookies, in seconds. See :ref:`topics-http-sessions`. +The age of session cookies, in seconds. See :doc:`/topics/http/sessions`. .. setting:: SESSION_COOKIE_DOMAIN @@ -1265,7 +1287,7 @@ Default: ``None`` The domain to use for session cookies. Set this to a string such as ``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard -domain cookie. See the :ref:`topics-http-sessions`. +domain cookie. See the :doc:`/topics/http/sessions`. .. setting:: SESSION_COOKIE_NAME @@ -1275,7 +1297,7 @@ SESSION_COOKIE_NAME Default: ``'sessionid'`` The name of the cookie to use for sessions. This can be whatever you want (but -should be different from ``LANGUAGE_COOKIE_NAME``). See the :ref:`topics-http-sessions`. +should be different from ``LANGUAGE_COOKIE_NAME``). See the :doc:`/topics/http/sessions`. .. setting:: SESSION_COOKIE_PATH @@ -1303,7 +1325,28 @@ Default: ``False`` Whether to use a secure cookie for the session cookie. If this is set to ``True``, the cookie will be marked as "secure," which means browsers may ensure that the cookie is only sent under an HTTPS connection. -See the :ref:`topics-http-sessions`. +See the :doc:`/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 :doc:`/topics/http/sessions`. .. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE @@ -1313,7 +1356,7 @@ SESSION_EXPIRE_AT_BROWSER_CLOSE Default: ``False`` Whether to expire the session when the user closes his or her browser. -See the :ref:`topics-http-sessions`. +See the :doc:`/topics/http/sessions`. .. setting:: SESSION_FILE_PATH @@ -1325,7 +1368,7 @@ SESSION_FILE_PATH Default: ``None`` If you're using file-based session storage, this sets the directory in -which Django will store session data. See :ref:`topics-http-sessions`. When +which Django will store session data. See :doc:`/topics/http/sessions`. When the default value (``None``) is used, Django will use the standard temporary directory for the system. @@ -1337,7 +1380,7 @@ SESSION_SAVE_EVERY_REQUEST Default: ``False`` Whether to save the session data on every request. See -:ref:`topics-http-sessions`. +:doc:`/topics/http/sessions`. .. setting:: SHORT_DATE_FORMAT @@ -1382,7 +1425,7 @@ The ID, as an integer, of the current site in the ``django_site`` database table. This is used so that application data can hook into specific site(s) and a single database can manage content for multiple sites. -See :ref:`ref-contrib-sites`. +See :doc:`/ref/contrib/sites`. .. _site framework docs: ../sites/ @@ -1405,8 +1448,8 @@ of items to be merged into the context. .. versionchanged:: 1.2 ``"django.contrib.messages.context_processors.messages"`` was added to the - default. For more information, see the :ref:`messages documentation - <ref-contrib-messages>`. + default. For more information, see the :doc:`messages documentation + </ref/contrib/messages>`. .. versionchanged:: 1.2 The auth context processor was moved in this release from its old location @@ -1440,7 +1483,7 @@ Default: ``()`` (Empty tuple) List of locations of the template source files, in search order. Note that these paths should use Unix-style forward slashes, even on Windows. -See :ref:`topics-templates`.. +See :doc:`/topics/templates`. .. setting:: TEMPLATE_LOADERS @@ -1456,7 +1499,7 @@ A tuple of template loader classes, specified as strings. Each ``Loader`` class knows how to import templates from a particular source. Optionally, a tuple can be used instead of a string. The first item in the tuple should be the ``Loader``'s module, subsequent items are passed to the ``Loader`` during initialization. See -:ref:`ref-templates-api`. +:doc:`/ref/templates/api`. .. setting:: TEMPLATE_STRING_IF_INVALID @@ -1479,7 +1522,7 @@ Default: ``'django.test.simple.DjangoTestSuiteRunner'`` Prior to 1.2, test runners were a function, not a class. The name of the class to use for starting the test suite. See -:ref:`topics-testing`. +:doc:`/topics/testing`. .. _Testing Django Applications: ../testing/ @@ -1531,7 +1574,7 @@ to be displayed. See also ``DATE_INPUT_FORMATS`` and ``DATETIME_INPUT_FORMATS``. -.. _datetime: http://docs.python.org/library/datetime.html#strftime-behavior +.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior .. setting:: TIME_ZONE @@ -1598,7 +1641,21 @@ Default: ``False`` 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`). +is installed (see :doc:`/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 @@ -1615,20 +1672,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..04243a87a4 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -1,5 +1,3 @@ -.. _ref-signals: - ======= Signals ======= @@ -8,11 +6,11 @@ A list of all the signals that Django sends. .. seealso:: - See the documentation on the :ref:`signal dispatcher <topics-signals>` for + See the documentation on the :doc:`signal dispatcher </topics/signals>` for information regarding how to register for and receive signals. - The :ref:`comment framework <ref-contrib-comments-index>` sends a :ref:`set - of comment-related signals <ref-contrib-comments-signals>`. + The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`set + of comment-related signals </ref/contrib/comments/signals>`. Model signals ============= @@ -33,9 +31,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 -------- @@ -61,7 +59,7 @@ Arguments sent with this signal: A dictionary of keyword arguments passed to :meth:`~django.db.models.Model.__init__`:. -For example, the :ref:`tutorial <intro-tutorial01>` has this line: +For example, the :doc:`tutorial </intro/tutorial01>` has this line: .. code-block:: python @@ -113,6 +111,9 @@ Arguments sent with this signal: ``instance`` The actual instance being saved. + ``using`` + The database alias being used. + post_save --------- @@ -133,6 +134,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 +154,9 @@ Arguments sent with this signal: ``instance`` The actual instance being deleted. + ``using`` + The database alias being used. + post_delete ----------- @@ -170,6 +177,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 +225,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 +238,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 +279,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 +308,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 @@ -313,7 +330,7 @@ Arguments that are sent with this signal: Management signals ================== -Signals sent by :ref:`django-admin <ref-django-admin>`. +Signals sent by :doc:`django-admin </ref/django-admin>`. post_syncdb ----------- @@ -376,8 +393,7 @@ Sent when Django begins processing an HTTP request. Arguments sent with this signal: ``sender`` - The handler class -- i.e. - :class:`django.core.handlers.modpython.ModPythonHandler` or + The handler class -- e.g. :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled the request. @@ -416,7 +432,7 @@ Test signals .. module:: django.test.signals :synopsis: Signals sent during testing. -Signals only sent when :ref:`running tests <topics-testing>`. +Signals only sent when :doc:`running tests </topics/testing>`. template_rendered ----------------- @@ -438,3 +454,39 @@ Arguments sent with this signal: context The :class:`~django.template.Context` with which the template was rendered. + +Database Wrappers +================= + +.. module:: django.db.backends + :synopsis: Core signals sent by the database wrapper. + +Signals sent by the database wrapper when a database connection is +initiated. + +connection_created +------------------ + +.. data:: django.db.backends.signals.connection_created + :module: + +.. versionadded:: 1.1 + +.. versionchanged:: 1.2 + The connection argument was added + +Sent when the database wrapper makes the initial connection to the +database. This is particularly useful if you'd like to send any post +connection commands to the SQL backend. + +Arguments sent with this signal: + + sender + The database wrapper class -- i.e. + :class: `django.db.backends.postgresql_psycopg2.DatabaseWrapper` or + :class: `django.db.backends.mysql.DatabaseWrapper`, etc. + + connection + The database connection that was opened. This can be used in a + multiple-database configuration to differentiate connection signals + from different databases. diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 3e267531de..2ac4e653c4 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -1,12 +1,10 @@ -.. _ref-templates-api: - ==================================================== The Django template language: For Python programmers ==================================================== This document explains the Django template system from a technical perspective -- how it works and how to extend it. If you're just looking for -reference on the language syntax, see :ref:`topics-templates`. +reference on the language syntax, see :doc:`/topics/templates`. If you're looking to use the Django template system as part of another application -- i.e., without the rest of the framework -- make sure to read @@ -323,7 +321,7 @@ and return a dictionary of items to be merged into the context. By default, .. versionadded:: 1.2 The ``'messages'`` context processor was added. For more information, see - the :ref:`messages documentation <ref-contrib-messages>`. + the :doc:`messages documentation </ref/contrib/messages>`. .. versionchanged:: 1.2 The auth context processor was moved in this release from its old location @@ -384,7 +382,7 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every logged in). * ``messages`` -- A list of messages (as strings) that have been set - via the :ref:`messages framework <ref-contrib-messages>`. + via the :doc:`messages framework </ref/contrib/messages>`. * ``perms`` -- An instance of ``django.core.context_processors.PermWrapper``, representing the @@ -397,7 +395,7 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every .. versionchanged:: 1.2 Prior to version 1.2, the ``messages`` variable was a lazy accessor for ``user.get_and_delete_messages()``. It has been changed to include any - messages added via the :ref:`messages framework <ref-contrib-messages>`. + messages added via the :doc:`messages framework </ref/contrib/messages>`. django.core.context_processors.debug ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -423,7 +421,7 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every * ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise, the value of the :setting:`LANGUAGE_CODE` setting. -See :ref:`topics-i18n` for more. +See :doc:`/topics/i18n/index` for more. django.core.context_processors.media ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -440,7 +438,7 @@ django.core.context_processors.csrf .. versionadded:: 1.2 This processor adds a token that is needed by the ``csrf_token`` template tag -for protection against :ref:`Cross Site Request Forgeries <ref-contrib-csrf>`. +for protection against :doc:`Cross Site Request Forgeries </ref/contrib/csrf>`. django.core.context_processors.request ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -458,7 +456,7 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every * ``messages`` -- A list of messages (as strings) that have been set via the user model (using ``user.message_set.create``) or through - the :ref:`messages framework <ref-contrib-messages>`. + the :doc:`messages framework </ref/contrib/messages>`. .. versionadded:: 1.2 This template context variable was previously supplied by the ``'auth'`` @@ -702,7 +700,7 @@ Configuring the template system in standalone mode Normally, Django will load all the configuration information it needs from its own default configuration file, combined with the settings in the module given -in the :setting:`DJANGO_SETTINGS_MODULE` environment variable. But if you're +in the :envvar:`DJANGO_SETTINGS_MODULE` environment variable. But if you're using the template system independently of the rest of Django, the environment variable approach isn't very convenient, because you probably want to configure the template system in line with the rest of your application rather than @@ -716,7 +714,7 @@ settings you wish to specify. You might want to consider setting at least :setting:`TEMPLATE_DIRS` (if you're going to use template loaders), :setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine) and :setting:`TEMPLATE_DEBUG`. All available settings are described in the -:ref:`settings documentation <ref-settings>`, and any setting starting with +:doc:`settings documentation </ref/settings>`, and any setting starting with ``TEMPLATE_`` is of obvious interest. .. _topic-template-alternate-language: diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 002aa3f416..4f33bd212c 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -1,5 +1,3 @@ -.. _ref-templates-builtins: - ================================== Built-in template tags and filters ================================== @@ -25,7 +23,7 @@ autoescape Control the current auto-escaping behavior. This tag takes either ``on`` or ``off`` as an argument and that determines whether auto-escaping is in effect -inside the block. +inside the block. The block is closed with an ``endautoescape`` ending tag. When auto-escaping is in effect, all variable content has HTML escaping applied to it before placing the result into the output (but after any filters have @@ -36,6 +34,12 @@ The only exceptions are variables that are already marked as "safe" from escaping, either by the code that populated the variable, or because it has had the ``safe`` or ``escape`` filters applied. +Sample usage:: + + {% autoescape on %} + {{ body }} + {% endautoescape %} + .. templatetag:: block block @@ -60,8 +64,8 @@ csrf_token In the Django 1.1.X series, this is a no-op tag that returns an empty string for future compatibility purposes. In Django 1.2 and later, it is used for CSRF -protection, as described in the documentation for :ref:`Cross Site Request -Forgeries <ref-contrib-csrf>`. +protection, as described in the documentation for :doc:`Cross Site Request +Forgeries </ref/contrib/csrf>`. .. templatetag:: cycle @@ -633,7 +637,7 @@ load Load a custom template tag set. -See :ref:`Custom tag and filter libraries <howto-custom-template-tags>` for more information. +See :doc:`Custom tag and filter libraries </howto/custom-template-tags>` for more information. .. templatetag:: now @@ -1883,6 +1887,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 +1908,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 @@ -2058,7 +2066,7 @@ django.contrib.humanize ~~~~~~~~~~~~~~~~~~~~~~~ A set of Django template filters useful for adding a "human touch" to data. See -:ref:`ref-contrib-humanize`. +:doc:`/ref/contrib/humanize`. django.contrib.markup ~~~~~~~~~~~~~~~~~~~~~ @@ -2069,13 +2077,13 @@ A collection of template filters that implement these common markup languages: * Markdown * ReST (ReStructured Text) -See :ref:`ref-contrib-markup`. +See the :doc:`markup documentation </ref/contrib/markup>`. django.contrib.webdesign ~~~~~~~~~~~~~~~~~~~~~~~~ A collection of template tags that can be useful while designing a website, -such as a generator of Lorem Ipsum text. See :ref:`ref-contrib-webdesign`. +such as a generator of Lorem Ipsum text. See :doc:`/ref/contrib/webdesign`. i18n ~~~~ diff --git a/docs/ref/templates/index.txt b/docs/ref/templates/index.txt index 6655b3da18..0aa4798a94 100644 --- a/docs/ref/templates/index.txt +++ b/docs/ref/templates/index.txt @@ -1,5 +1,3 @@ -.. _ref-templates-index: - ========= Templates ========= @@ -18,4 +16,4 @@ an understanding of HTML; no knowledge of Python is required. .. seealso:: For information on writing your own custom tags and filters, see - :ref:`howto-custom-template-tags`. + :doc:`/howto/custom-template-tags`. diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index a6149119bf..8e110af5d5 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -1,5 +1,3 @@ -.. _ref-unicode: - ============ Unicode data ============ @@ -95,7 +93,7 @@ Calling ``unicode()`` with the lazy translation as the argument will generate a Unicode string in the current locale. For more details about lazy translation objects, refer to the -:ref:`internationalization <topics-i18n>` documentation. +:doc:`internationalization </topics/i18n/index>` documentation. Useful utility functions ------------------------ diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index e64b3868b9..39b01df0be 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -1,5 +1,3 @@ -.. _ref-utils: - ============ Django Utils ============ @@ -32,7 +30,7 @@ into account when building its cache key. Requests with the same path but different header content for headers named in ``Vary`` need to get different cache keys to prevent delivery of wrong content. -For example, :ref:`internationalization <topics-i18n>` middleware would need +For example, :doc:`internationalization </topics/i18n/index>` middleware would need to distinguish caches by the ``Accept-language`` header. .. function:: patch_cache_control(response, **kwargs) @@ -395,7 +393,7 @@ applied once). :synopsis: Internationalization support. For a complete discussion on the usage of the following see the -:ref:`Internationalization documentation <topics-i18n-internationalization>`. +:doc:`Internationalization documentation </topics/i18n/internationalization>`. .. function:: gettext(message) diff --git a/docs/ref/validators.txt b/docs/ref/validators.txt index bbba84c7f9..4937512e46 100644 --- a/docs/ref/validators.txt +++ b/docs/ref/validators.txt @@ -1,10 +1,10 @@ -.. _ref-validators: - ========== Validators ========== .. versionadded:: 1.2 +.. module:: django.core.validators + :synopsis: Validation utilities and base classes Writing validators ================== @@ -40,12 +40,12 @@ use the same validator with forms:: How validators are run ====================== -See the :ref:`form validation <ref-forms-validation>` for more information on +See the :doc:`form validation </ref/forms/validation>` for more information on how validators are run in forms, and :ref:`Validating objects <validating-objects>` for how they're run in models. Note that validators will not be run automatically when you save a model, but if you are using a ``ModelForm``, it will run your validators on any fields that are included in -your form. See the :ref:`ModelForm documentation <topics-forms-modelforms>` +your form. See the :doc:`ModelForm documentation </topics/forms/modelforms>` for information on how model validation interacts with forms. Built-in validators diff --git a/docs/releases/0.95.txt b/docs/releases/0.95.txt index b74160128b..7409bff1c0 100644 --- a/docs/releases/0.95.txt +++ b/docs/releases/0.95.txt @@ -1,5 +1,3 @@ -.. _releases-0.95: - ================================= Django version 0.95 release notes ================================= @@ -100,7 +98,7 @@ Problem reports and getting help ================================ Need help resolving a problem with Django? The documentation in the distribution -is also available online_ at the `Django Web site`_. The :ref:`FAQ <faq-index>` +is also available online_ at the `Django Web site`_. The :doc:`FAQ </faq/index>` document is especially recommended, as it contains a number of issues that come up time and again. diff --git a/docs/releases/0.96.txt b/docs/releases/0.96.txt index 8d795acebd..1224360e3f 100644 --- a/docs/releases/0.96.txt +++ b/docs/releases/0.96.txt @@ -1,5 +1,3 @@ -.. _releases-0.96: - ================================= Django version 0.96 release notes ================================= diff --git a/docs/releases/1.0-alpha-1.txt b/docs/releases/1.0-alpha-1.txt index caee575cb2..82846be44a 100644 --- a/docs/releases/1.0-alpha-1.txt +++ b/docs/releases/1.0-alpha-1.txt @@ -1,5 +1,3 @@ -.. _releases-1.0-alpha-1: - ================================ Django 1.0 alpha release notes ================================ @@ -34,7 +32,7 @@ Refactored admin application (newforms-admin) documentation for the admin application is available online in the official Django documentation: - :ref:`admin reference <ref-contrib-admin>` + :doc:`admin reference </ref/contrib/admin/index>` Improved Unicode handling Django's internals have been refactored to use Unicode throughout; @@ -45,7 +43,7 @@ Improved Unicode handling Unicode gracefully. Details are available in Django's Unicode-handling documentation: - :ref:`unicode reference <ref-unicode>` + :doc:`unicode reference </ref/unicode>` An improved Django ORM Django's object-relational mapper -- the component which provides @@ -156,7 +154,7 @@ to join the discussions there. Django's online documentation also includes pointers on how to contribute to Django: - :ref:`contributing to Django <internals-contributing>` + :doc:`contributing to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed diff --git a/docs/releases/1.0-alpha-2.txt b/docs/releases/1.0-alpha-2.txt index 5cbd777204..83e2e2e14a 100644 --- a/docs/releases/1.0-alpha-2.txt +++ b/docs/releases/1.0-alpha-2.txt @@ -1,5 +1,3 @@ -.. _releases-1.0-alpha-2: - ================================ Django 1.0 alpha 2 release notes ================================ @@ -21,8 +19,8 @@ What's new in Django 1.0 alpha 2 Django's development trunk has been the site of nearly constant activity over the past year, with several major new features landing since the 0.96 release. -For features which were new as of Django 1.0 alpha 1, see :ref:`the 1.0 alpha 1 -release notes <releases-1.0-alpha-1`. Since the 1.0 alpha 1 release several new +For features which were new as of Django 1.0 alpha 1, see :doc:`the 1.0 alpha 1 +release notes </releases/1.0-alpha-1>`. Since the 1.0 alpha 1 release several new features have landed, including: ``django.contrib.gis`` (`GeoDjango`_) @@ -37,8 +35,8 @@ features have landed, including: Pluggable file storage Django's built-in ``FileField`` and ``ImageField`` now can take advantage of pluggable file-storage backends, allowing extensive customization of where - and how uploaded files get stored by Django. For details, see :ref:`the - files documentation <topics-files>`; big thanks go to Marty Alchin for + and how uploaded files get stored by Django. For details, see :doc:`the + files documentation </topics/files>`; big thanks go to Marty Alchin for putting in the hard work to get this completed. Jython compatibility @@ -51,11 +49,11 @@ Jython compatibility There are many other new features and improvements in this release, including two major performance boosts: strings marked for translation using -:ref:`Django's internationalization system <topics-i18n>` now consume far less +:doc:`Django's internationalization system </topics/i18n/index>` now consume far less memory, and Django's internal dispatcher -- which is invoked frequently during request/response processing and when working with Django's object-relational mapper -- is now significantly faster. - + .. _GeoDjango: http://geodjango.org/ .. _Geographic Information Systems: http://en.wikipedia.org/wiki/Geographic_information_system .. _Its documentation: http://geodjango.org/docs/ @@ -131,7 +129,7 @@ to join the discussions there. Django's online documentation also includes pointers on how to contribute to Django: - :ref:`contributing to Django <internals-contributing>` + :doc:`contributing to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed diff --git a/docs/releases/1.0-beta-2.txt b/docs/releases/1.0-beta-2.txt index 89b9233576..eabd6b744b 100644 --- a/docs/releases/1.0-beta-2.txt +++ b/docs/releases/1.0-beta-2.txt @@ -1,5 +1,3 @@ -.. _releases-1.0-beta-2: - =============================== Django 1.0 beta 2 release notes =============================== @@ -21,11 +19,11 @@ What's new in Django 1.0 beta 2 Django's development trunk has been the site of nearly constant activity over the past year, with several major new features landing since the 0.96 release. For features which were new as of Django 1.0 -alpha 1, see :ref:`the 1.0 alpha 1 release notes -<releases-1.0-alpha-1>`. For features which were new as of Django 1.0 -alpha 2, see :ref:`the 1.0 alpha 2 release notes -<releases-1.0-alpha-2>`. For features which were new as of Django 1.0 -beta 1, see :ref:`the 1.0 beta 1 release notes <releases-1.0-beta>`. +alpha 1, see :doc:`the 1.0 alpha 1 release notes +</releases/1.0-alpha-1>`. For features which were new as of Django 1.0 +alpha 2, see :doc:`the 1.0 alpha 2 release notes +</releases/1.0-alpha-2>`. For features which were new as of Django 1.0 +beta 1, see :doc:`the 1.0 beta 1 release notes </releases/1.0-beta>`. This beta release includes two major features: @@ -33,9 +31,9 @@ Refactored ``django.contrib.comments`` As part of a Google Summer of Code project, Thejaswi Puthraya carried out a major rewrite and refactoring of Django's bundled comment system, greatly increasing its flexibility and - customizability. :ref:`Full documentation - <ref-contrib-comments-index>` is available, as well as :ref:`an - upgrade guide <ref-contrib-comments-upgrade>` if you were using + customizability. :doc:`Full documentation + </ref/contrib/comments/index>` is available, as well as :doc:`an + upgrade guide </ref/contrib/comments/upgrade>` if you were using the previous incarnation of the comments application.. Refactored documentation @@ -59,8 +57,8 @@ Also, as part of its ongoing deprecation process, Django's old form-handling system has been removed; this means ``django.oldforms`` no longer exists, and its various API hooks (such as automatic manipulators) are no longer present in Django. This system has been -completely replaced by :ref:`the new form-handling system -<topics-forms-index>` in ``django.forms``. +completely replaced by :doc:`the new form-handling system +</topics/forms/index>` in ``django.forms``. The Django 1.0 roadmap @@ -114,7 +112,7 @@ to join the discussions there. Django's online documentation also includes pointers on how to contribute to Django: - :ref:`contributing to Django <internals-contributing>` + :doc:`contributing to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed diff --git a/docs/releases/1.0-beta.txt b/docs/releases/1.0-beta.txt index c1957a75a4..9e07e6c03f 100644 --- a/docs/releases/1.0-beta.txt +++ b/docs/releases/1.0-beta.txt @@ -1,5 +1,3 @@ -.. _releases-1.0-beta: - =============================== Django 1.0 beta 1 release notes =============================== @@ -20,9 +18,9 @@ What's new in Django 1.0 beta 1 Django's development trunk has been the site of nearly constant activity over the past year, with several major new features landing since the 0.96 release. -For features which were new as of Django 1.0 alpha 1, see :ref:`the 1.0 alpha 1 -release notes <releases-1.0-alpha-1>`. For features which were new as of Django -1.0 alpha 2, see :ref:`the 1.0 alpha 2 release notes <releases-1.0-alpha-2>`. +For features which were new as of Django 1.0 alpha 1, see :doc:`the 1.0 alpha 1 +release notes </releases/1.0-alpha-1>`. For features which were new as of Django +1.0 alpha 2, see :doc:`the 1.0 alpha 2 release notes </releases/1.0-alpha-2>`. This beta release does not contain any major new features, but does include several smaller updates and improvements to Django: @@ -38,7 +36,7 @@ Improved flexibility in the admin interface (``django.contrib.admin``), introduced in Django 1.0 alpha 1, two new hooks have been added to allow customized pre- and post-save handling of model instances in the admin. Full - details are in :ref:`the admin documentation <ref-contrib-admin>`. + details are in :doc:`the admin documentation </ref/contrib/admin/index>`. ``INSERT``/``UPDATE`` distinction Although Django's default behavior of having a model's ``save()`` @@ -59,7 +57,7 @@ Split ``CacheMiddleware`` flexibility for situations where combining these functions into a single middleware posed problems. Full details, including updated notes on appropriate use, are in - :ref:`the caching documentation <topics-cache>`. + :doc:`the caching documentation </topics/cache>`. Removal of deprecated features A number of features and methods which had previously been marked @@ -148,7 +146,7 @@ to join the discussions there. Django's online documentation also includes pointers on how to contribute to Django: - :ref:`contributing to Django <internals-contributing>` + :doc:`contributing to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed diff --git a/docs/releases/1.0-porting-guide.txt b/docs/releases/1.0-porting-guide.txt index f87da1c8d0..95b9efe255 100644 --- a/docs/releases/1.0-porting-guide.txt +++ b/docs/releases/1.0-porting-guide.txt @@ -13,7 +13,7 @@ Changes`_ for a list of a bunch of less-common compatibility issues. .. seealso:: - The :ref:`1.0 release notes <releases-1.0>`. That document explains the new + The :doc:`1.0 release notes </releases/1.0>`. That document explains the new features in 1.0 more deeply; the porting guide is more concerned with helping you quickly update your code. @@ -31,7 +31,7 @@ now uses Unicode strings throughout. In most places, raw strings will continue to work, but updating to use Unicode literals will prevent some obscure problems. -See :ref:`ref-unicode` for full details. +See :doc:`/ref/unicode` for full details. Models ------ @@ -211,7 +211,7 @@ New (1.0):: can be found on the `NewformsAdminBranch wiki page`__ * The new admin comes with a ton of new features; you can read about them in - the :ref:`admin documentation <ref-contrib-admin>`. + the :doc:`admin documentation </ref/contrib/admin/index>`. __ http://code.djangoproject.com/wiki/NewformsAdminBranch @@ -271,7 +271,7 @@ New:: If you're using the old forms system (formerly known as ``django.forms`` and ``django.oldforms``), you'll have to rewrite your forms. A good place to start -is the :ref:`forms documentation <topics-forms-index>` +is the :doc:`forms documentation </topics/forms/index>` Handle uploaded files using the new API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -318,7 +318,7 @@ Old (0.96) New (1.0) Note that the ``width`` and ``height`` attributes only make sense for :class:`~django.db.models.ImageField` fields. More details can be found in the -:ref:`model API <ref-models-fields>` documentation. +:doc:`model API </ref/models/fields>` documentation. Use ``Paginator`` instead of ``ObjectPaginator`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -392,7 +392,7 @@ Comments If you were using Django 0.96's ``django.contrib.comments`` app, you'll need to upgrade to the new comments app introduced in 1.0. See -:ref:`ref-contrib-comments-upgrade` for details. +:doc:`/ref/contrib/comments/upgrade` for details. Template tags ------------- diff --git a/docs/releases/1.0.1.txt b/docs/releases/1.0.1.txt index ce101bed03..780dc53c1f 100644 --- a/docs/releases/1.0.1.txt +++ b/docs/releases/1.0.1.txt @@ -1,5 +1,3 @@ -.. _releases-1.0.1: - ========================== Django 1.0.1 release notes ========================== diff --git a/docs/releases/1.0.2.txt b/docs/releases/1.0.2.txt index 136a833f05..b34522a08d 100644 --- a/docs/releases/1.0.2.txt +++ b/docs/releases/1.0.2.txt @@ -1,5 +1,3 @@ -.. _releases-1.0.2: - ========================== Django 1.0.2 release notes ========================== @@ -9,7 +7,7 @@ Welcome to Django 1.0.2! This is the second "bugfix" release in the Django 1.0 series, improving the stability and performance of the Django 1.0 codebase. As such, Django 1.0.2 contains no new features (and, pursuant to -:ref:`our compatibility policy <misc-api-stability>`, maintains backwards compatibility with Django +:doc:`our compatibility policy </misc/api-stability>`, maintains backwards compatibility with Django 1.0.0), but does contain a number of fixes and other improvements. Django 1.0.2 is a recommended upgrade for any development or deployment currently using or targeting Django 1.0. @@ -27,7 +25,7 @@ Django's unit-test suite. Django 1.0.2 contains updated packaging scripts, and the release package contains the directories omitted from Django 1.0.1. As such, this release contains all of the fixes and improvements from Django -1.0.1; see :ref:`the Django 1.0.1 release notes <releases-1.0.1>` for +1.0.1; see :doc:`the Django 1.0.1 release notes </releases/1.0.1>` for details. Additionally, in the period since Django 1.0.1 was released: diff --git a/docs/releases/1.0.txt b/docs/releases/1.0.txt index 6827a62cc8..359490aad3 100644 --- a/docs/releases/1.0.txt +++ b/docs/releases/1.0.txt @@ -1,5 +1,3 @@ -.. _releases-1.0: - ======================== Django 1.0 release notes ======================== @@ -24,12 +22,12 @@ contributions overtake those made privately. Stability and forwards-compatibility ==================================== -:ref:`The release of Django 1.0 <releases-1.0>` comes with a promise of API +:doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API stability and forwards-compatibility. In a nutshell, this means that code you develop against Django 1.0 will continue to work against 1.1 unchanged, and you should need to make only minor changes for any 1.X release. -See the :ref:`API stability guide <misc-api-stability>` for full details. +See the :doc:`API stability guide </misc/api-stability>` for full details. Backwards-incompatible changes ============================== @@ -42,7 +40,7 @@ detailed porting guide: :maxdepth: 1 1.0-porting-guide - + A complete list of backwards-incompatible changes can be found at http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges. @@ -60,9 +58,9 @@ In fact, new documentation is one of our favorite features of Django 1.0, so we might as well start there. First, there's a new documentation site: http://docs.djangoproject.com/ - + The documentation has been greatly improved, cleaned up, and generally made -awesome. There's now dedicated search, indexes, and more. +awesome. There's now dedicated search, indexes, and more. We can't possibly document everything that's new in 1.0, but the documentation will be your definitive guide. Anywhere you see something like: @@ -85,7 +83,7 @@ Django's new form-handling library (introduced in the 0.96 release as redesigned with extensibility and customization in mind. Full documentation for the admin application is available online in the official Django documentation: -See the :ref:`admin reference <ref-contrib-admin>` for details +See the :doc:`admin reference </ref/contrib/admin/index>` for details Improved Unicode handling ------------------------- @@ -97,7 +95,7 @@ interoperability with third-party libraries and systems which may or may not handle Unicode gracefully. Details are available in Django's Unicode-handling documentation. -See :ref:`ref-unicode`. +See :doc:`/ref/unicode`. An improved ORM --------------- @@ -142,8 +140,8 @@ Pluggable file storage Django's built-in ``FileField`` and ``ImageField`` now can take advantage of pluggable file-storage backends, allowing extensive customization of where and -how uploaded files get stored by Django. For details, see :ref:`the files -documentation <topics-files>`; big thanks go to Marty Alchin for putting in the +how uploaded files get stored by Django. For details, see :doc:`the files +documentation </topics/files>`; big thanks go to Marty Alchin for putting in the hard work to get this completed. Jython compatibility @@ -155,7 +153,7 @@ Django's codebase has been refactored to remove incompatibilities with on the Java Virtual Machine. Django is now compatible with the forthcoming Jython 2.5 release. -See :ref:`howto-jython`. +See :doc:`/howto/jython`. .. _Jython: http://www.jython.org/ @@ -187,17 +185,17 @@ handle the two parts of caching (inserting into and reading from the cache) separately, offering additional flexibility for situations where combining these functions into a single middleware posed problems. -Full details, including updated notes on appropriate use, are in :ref:`the -caching documentation <topics-cache>`. +Full details, including updated notes on appropriate use, are in :doc:`the +caching documentation </topics/cache>`. Refactored ``django.contrib.comments`` -------------------------------------- As part of a Google Summer of Code project, Thejaswi Puthraya carried out a major rewrite and refactoring of Django's bundled comment system, greatly -increasing its flexibility and customizability. :ref:`Full documentation -<ref-contrib-comments-index>` is available, as well as :ref:`an upgrade guide -<ref-contrib-comments-upgrade>` if you were using the previous incarnation of +increasing its flexibility and customizability. :doc:`Full documentation +</ref/contrib/comments/index>` is available, as well as :doc:`an upgrade guide +</ref/contrib/comments/upgrade>` if you were using the previous incarnation of the comments application. Removal of deprecated features @@ -240,7 +238,7 @@ Caveats with support of certain databases ----------------------------------------- Django attempts to support as many features as possible on all database -backends. However, not all database backends are alike, and in particular many of the supported database differ greatly from version to version. It's a good idea to checkout our :ref:`notes on supported database <ref-databases>`: +backends. However, not all database backends are alike, and in particular many of the supported database differ greatly from version to version. It's a good idea to checkout our :doc:`notes on supported database </ref/databases>`: - :ref:`mysql-notes` - :ref:`sqlite-notes` diff --git a/docs/releases/1.1-alpha-1.txt b/docs/releases/1.1-alpha-1.txt index 664c354561..b15a2a423c 100644 --- a/docs/releases/1.1-alpha-1.txt +++ b/docs/releases/1.1-alpha-1.txt @@ -1,5 +1,3 @@ -.. _releases-1.1-alpha-1: - ================================ Django 1.1 alpha 1 release notes ================================ @@ -37,8 +35,8 @@ results of the aggregate directly, or else annotate the objects in a :class:`QuerySet` with the results of the aggregate query. This feature is available as new :meth:`QuerySet.aggregate()`` and -:meth:`QuerySet.annotate()`` methods, and is covered in detail in :ref:`the ORM -aggregation documentation <topics-db-aggregation>` +:meth:`QuerySet.annotate()`` methods, and is covered in detail in :doc:`the ORM +aggregation documentation </topics/db/aggregation>` Query expressions ~~~~~~~~~~~~~~~~~ @@ -53,7 +51,7 @@ Performance improvements .. currentmodule:: django.test -Tests written using Django's :ref:`testing framework <topics-testing>` now run +Tests written using Django's :doc:`testing framework </topics/testing>` now run dramatically faster (as much as 10 times faster in many cases). This was accomplished through the introduction of transaction-based tests: when @@ -68,7 +66,7 @@ Other improvements Other new features and changes introduced since Django 1.0 include: -* The :ref:`CSRF protection middleware <ref-contrib-csrf>` has been split into +* The :doc:`CSRF protection middleware </ref/contrib/csrf>` has been split into two classes -- ``CsrfViewMiddleware`` checks incoming requests, and ``CsrfResponseMiddleware`` processes outgoing responses. The combined ``CsrfMiddleware`` class (which does both) remains for @@ -85,13 +83,13 @@ Other new features and changes introduced since Django 1.0 include: * The ``include()`` function in Django URLconf modules can now accept sequences of URL patterns (generated by ``patterns()``) in addition to module names. -* Instances of Django forms (see :ref:`the forms overview <topics-forms-index>`) +* Instances of Django forms (see :doc:`the forms overview </topics/forms/index>`) now have two additional methods, ``hidden_fields()`` and ``visible_fields()``, which return the list of hidden -- i.e., ``<input type="hidden">`` -- and visible fields on the form, respectively. -* The ``redirect_to`` generic view (see :ref:`the generic views documentation - <ref-generic-views>`) now accepts an additional keyword argument +* The ``redirect_to`` generic view (see :doc:`the generic views documentation + </ref/generic-views>`) now accepts an additional keyword argument ``permanent``. If ``permanent`` is ``True``, the view will emit an HTTP permanent redirect (status code 301). If ``False``, the view will emit an HTTP temporary redirect (status code 302). @@ -104,8 +102,8 @@ Other new features and changes introduced since Django 1.0 include: * The ``{% for %}`` tag in Django's template language now accepts an optional ``{% empty %}`` clause, to be displayed when ``{% for %}`` is asked to loop - over an empty sequence. See :ref:`the list of built-in template tags - <ref-templates-builtins>` for examples of this. + over an empty sequence. See :doc:`the list of built-in template tags + </ref/templates/builtins>` for examples of this. The Django 1.1 roadmap ====================== @@ -153,7 +151,7 @@ discussions there. Django's online documentation also includes pointers on how to contribute to Django: - * :ref:`How to contribute to Django <internals-contributing>` + * :doc:`How to contribute to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed bugfixes -- are always welcome and diff --git a/docs/releases/1.1-beta-1.txt b/docs/releases/1.1-beta-1.txt index a433efc33c..83423962b3 100644 --- a/docs/releases/1.1-beta-1.txt +++ b/docs/releases/1.1-beta-1.txt @@ -1,5 +1,3 @@ -.. _releases-1.1-beta-1: - =============================== Django 1.1 beta 1 release notes =============================== @@ -22,7 +20,7 @@ What's new in Django 1.1 beta 1 .. seealso:: - The :ref:`1.1 alpha release notes <releases-1.1-alpha-1>`, which has a + The :doc:`1.1 alpha release notes </releases/1.1-alpha-1>`, which has a list of everything new between Django 1.0 and Django 1.1 alpha. Model improvements @@ -71,8 +69,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 ------------------ @@ -90,7 +89,7 @@ up as form widgets on the list pages, and can be edited and saved in bulk. Admin "actions" ~~~~~~~~~~~~~~~ -You can now define :ref:`admin actions <ref-contrib-admin-actions>` that can perform +You can now define :doc:`admin actions </ref/contrib/admin/actions>` that can perform some action to a group of models in bulk. Users will be able to select objects on the change list page and then apply these bulk actions to all selected objects. @@ -103,23 +102,23 @@ Testing improvements .. currentmodule:: django.test.client A couple of small but very useful improvements have been made to the -:ref:`testing framework <topics-testing>`: +:doc:`testing framework </topics/testing>`: * 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 --------------------------- -Django now has much better support for :ref:`conditional view processing -<topics-conditional-processing>` using the standard ``ETag`` and +Django now has much better support for :doc:`conditional view processing +</topics/conditional-view-processing>` using the standard ``ETag`` and ``Last-Modified`` HTTP headers. This means you can now easily short-circuit view processing by testing less-expensive conditions. For many views this can lead to a serious improvement in speed and reduction in bandwidth. @@ -133,23 +132,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 + + * :doc:`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 + + * Django now can :doc:`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 +182,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,9 +194,9 @@ 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>` + * :doc:`How to contribute to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed bugfixes -- are always welcome and diff --git a/docs/releases/1.1-rc-1.txt b/docs/releases/1.1-rc-1.txt index bda424800e..f74444f1f9 100644 --- a/docs/releases/1.1-rc-1.txt +++ b/docs/releases/1.1-rc-1.txt @@ -1,5 +1,3 @@ -.. _releases-1.1-rc-1: - ============================= Django 1.1 RC 1 release notes ============================= @@ -30,8 +28,8 @@ contains only one new feature (see below); work leading up to this release candidate has instead been focused on bugfixing, particularly on the new features introduced prior to the 1.1 beta. -For an overview of those features, consult :ref:`the Django 1.1 beta -release notes <releases-1.1-beta-1>`. +For an overview of those features, consult :doc:`the Django 1.1 beta +release notes </releases/1.1-beta-1>`. URL namespaces @@ -104,7 +102,7 @@ discussions there. Django's online documentation also includes pointers on how to contribute to Django: - * :ref:`How to contribute to Django <internals-contributing>` + * :doc:`How to contribute to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed bugfixes -- are always welcome and diff --git a/docs/releases/1.1.2.txt b/docs/releases/1.1.2.txt index 3e5355f231..90a69759bf 100644 --- a/docs/releases/1.1.2.txt +++ b/docs/releases/1.1.2.txt @@ -1,5 +1,3 @@ -.. _releases-1.1.2: - ========================== Django 1.1.2 release notes ========================== @@ -15,7 +13,7 @@ improvements. Django 1.1.2 is a recommended upgrade for any development or deployment currently using or targeting Django 1.1. For full details on the new features, backwards incompatibilities, and -deprecated features in the 1.1 branch, see the :ref:`releases-1.1`. +deprecated features in the 1.1 branch, see the :doc:`/releases/1.1`. Backwards-incompatible changes in 1.1.2 ======================================= diff --git a/docs/releases/1.1.txt b/docs/releases/1.1.txt index edb7cf1af2..39cb0ab2b0 100644 --- a/docs/releases/1.1.txt +++ b/docs/releases/1.1.txt @@ -1,5 +1,3 @@ -.. _releases-1.1: - ======================== Django 1.1 release notes ======================== @@ -19,7 +17,7 @@ fixes, and an easy upgrade path from Django 1.0. Backwards-incompatible changes in 1.1 ===================================== -Django has a policy of :ref:`API stability <misc-api-stability>`. This means +Django has a policy of :doc:`API stability </misc/api-stability>`. This means that, in general, code you develop against Django 1.0 should continue to work against 1.1 unchanged. However, we do sometimes make backwards-incompatible changes if they're necessary to resolve bugs, and there are a handful of such @@ -176,7 +174,7 @@ be upgraded to a ``DeprecationWarning``, which will be displayed loudly. Django 1.3 will remove ``AdminSite.root()`` entirely. For more details on our deprecation policies and strategy, see -:ref:`internals-release-process`. +:doc:`/internals/release-process`. What's new in Django 1.1 ======================== @@ -203,8 +201,8 @@ results of the aggregate directly, or else annotate the objects in a :class:`QuerySet` with the results of the aggregate query. This feature is available as new :meth:`QuerySet.aggregate()`` and -:meth:`QuerySet.annotate()`` methods, and is covered in detail in :ref:`the ORM -aggregation documentation <topics-db-aggregation>`. +:meth:`QuerySet.annotate()`` methods, and is covered in detail in :doc:`the ORM +aggregation documentation </topics/db/aggregation>`. Query expressions ~~~~~~~~~~~~~~~~~ @@ -258,21 +256,22 @@ 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 -------------------- -A few notable improvements have been made to the :ref:`testing framework -<topics-testing>`. +A few notable improvements have been made to the :doc:`testing framework +</topics/testing>`. Test performance improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. currentmodule:: django.test -Tests written using Django's :ref:`testing framework <topics-testing>` now run +Tests written using Django's :doc:`testing framework </topics/testing>` now run dramatically faster (as much as 10 times faster in many cases). This was accomplished through the introduction of transaction-based tests: when @@ -315,7 +314,7 @@ up as form widgets on the list pages, and can be edited and saved in bulk. Admin "actions" ~~~~~~~~~~~~~~~ -You can now define :ref:`admin actions <ref-contrib-admin-actions>` that can +You can now define :doc:`admin actions </ref/contrib/admin/actions>` that can perform some action to a group of models in bulk. Users will be able to select objects on the change list page and then apply these bulk actions to all selected objects. @@ -326,8 +325,8 @@ one fell swoop. Conditional view processing --------------------------- -Django now has much better support for :ref:`conditional view processing -<topics-conditional-processing>` using the standard ``ETag`` and +Django now has much better support for :doc:`conditional view processing +</topics/conditional-view-processing>` using the standard ``ETag`` and ``Last-Modified`` HTTP headers. This means you can now easily short-circuit view processing by testing less-expensive conditions. For many views this can lead to a serious improvement in speed and reduction in bandwidth. @@ -375,7 +374,7 @@ Other improvements Other new features and changes introduced since Django 1.0 include: -* The :ref:`CSRF protection middleware <ref-contrib-csrf>` has been split into +* The :doc:`CSRF protection middleware </ref/contrib/csrf>` has been split into two classes -- ``CsrfViewMiddleware`` checks incoming requests, and ``CsrfResponseMiddleware`` processes outgoing responses. The combined ``CsrfMiddleware`` class (which does both) remains for @@ -392,13 +391,13 @@ Other new features and changes introduced since Django 1.0 include: * The ``include()`` function in Django URLconf modules can now accept sequences of URL patterns (generated by ``patterns()``) in addition to module names. -* Instances of Django forms (see :ref:`the forms overview <topics-forms-index>`) +* Instances of Django forms (see :doc:`the forms overview </topics/forms/index>`) now have two additional methods, ``hidden_fields()`` and ``visible_fields()``, which return the list of hidden -- i.e., ``<input type="hidden">`` -- and visible fields on the form, respectively. -* The ``redirect_to`` generic view (see :ref:`the generic views documentation - <ref-generic-views>`) now accepts an additional keyword argument +* The ``redirect_to`` generic view (see :doc:`the generic views documentation + </ref/generic-views>`) now accepts an additional keyword argument ``permanent``. If ``permanent`` is ``True``, the view will emit an HTTP permanent redirect (status code 301). If ``False``, the view will emit an HTTP temporary redirect (status code 302). @@ -411,8 +410,8 @@ Other new features and changes introduced since Django 1.0 include: * The ``{% for %}`` tag in Django's template language now accepts an optional ``{% empty %}`` clause, to be displayed when ``{% for %}`` is asked to loop - over an empty sequence. See :ref:`the list of built-in template tags - <ref-templates-builtins>` for examples of this. + over an empty sequence. See :doc:`the list of built-in template tags + </ref/templates/builtins>` for examples of this. * The :djadmin:`dumpdata` management command now accepts individual model names as arguments, allowing you to export the data just from @@ -421,14 +420,14 @@ Other new features and changes introduced since Django 1.0 include: * 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 +* :doc:`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 +* Django now can :doc:`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 @@ -455,7 +454,7 @@ join the discussions! Django's online documentation also includes pointers on how to contribute to Django: - * :ref:`How to contribute to Django <internals-contributing>` + * :doc:`How to contribute to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed bugfixes -- are always welcome and diff --git a/docs/releases/1.2-alpha-1.txt b/docs/releases/1.2-alpha-1.txt index 1e9d4422ce..4144a9a3a9 100644 --- a/docs/releases/1.2-alpha-1.txt +++ b/docs/releases/1.2-alpha-1.txt @@ -1,5 +1,3 @@ -.. _releases-1.2-alpha-1: - ================================ Django 1.2 alpha 1 release notes ================================ @@ -25,7 +23,7 @@ CSRF Protection --------------- There have been large changes to the way that CSRF protection works, detailed in -:ref:`the CSRF documentaton <ref-contrib-csrf>`. The following are the major +:doc:`the CSRF documentaton </ref/contrib/csrf>`. The following are the major changes that developers must be aware of: * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated, and @@ -303,7 +301,7 @@ User Messages API The API for storing messages in the user ``Message`` model (via ``user.message_set.create``) is now deprecated and will be removed in Django -1.4 according to the standard :ref:`release process <internals-release-process>`. +1.4 according to the standard :doc:`release process </internals/release-process>`. To upgrade your code, you need to replace any instances of:: @@ -327,7 +325,7 @@ with:: ... For more information, see the full -:ref:`messages documentation <ref-contrib-messages>`. You should begin to +:doc:`messages documentation </ref/contrib/messages>`. You should begin to update your code to use the new API immediately. Date format helper functions @@ -378,8 +376,8 @@ release cycle. Some minor features will continue development until the CSRF support ------------ -Django now has much improved protection against :ref:`Cross-Site -Request Forgery (CSRF) attacks<ref-contrib-csrf>`. This type of attack +Django now has much improved protection against :doc:`Cross-Site +Request Forgery (CSRF) attacks</ref/contrib/csrf>`. This type of attack occurs when a malicious Web site contains a link, a form button or some javascript that is intended to perform some action on your Web site, using the credentials of a logged-in user who visits the @@ -395,7 +393,7 @@ You can now :ref:`configure the way that Django sends e-mail can now choose a configurable e-mail backend to send messages. If your hosting provider uses a sandbox or some other non-SMTP technique for sending mail, you can now construct an e-mail backend that will allow -Django's standard :ref:`mail sending methods<topics-email>` to use +Django's standard :doc:`mail sending methods</topics/email>` to use those facilities. This also makes it easier to debug mail sending - Django ships with @@ -408,8 +406,8 @@ e-mail to be :ref:`thrown away<topic-email-dummy-backend>`. Messages Framework ------------------ -Django now includes a robust and configurable :ref:`messages framework -<ref-contrib-messages>` with built-in support for cookie- and session-based +Django now includes a robust and configurable :doc:`messages framework +</ref/contrib/messages>` with built-in support for cookie- and session-based messaging, for both anonymous and authenticated clients. The messages framework replaces the deprecated user message API and allows you to temporarily store messages in one request and retrieve them for display in a subsequent request @@ -418,8 +416,8 @@ messages in one request and retrieve them for display in a subsequent request Support for multiple databases ------------------------------ -Django 1.2 adds the ability to use :ref:`more than one database -<topics-db-multi-db>` in your Django project. Queries can be +Django 1.2 adds the ability to use :doc:`more than one database +</topics/db/multi-db>` in your Django project. Queries can be issued at a specific database with the `using()` method on querysets; individual objects can be saved to a specific database by providing a ``using`` argument when you save the instance. @@ -500,7 +498,7 @@ from the test run that reports details of the tests run before the interruption. Improved localization --------------------- -Django's :ref:`internationalization framework <topics-i18n>` has been +Django's :doc:`internationalization framework </topics/i18n/index>` has been expanded by locale aware formatting and form processing. That means, if enabled, dates and numbers on templates will be displayed using the format specified for the current locale. Django will also use localized formats @@ -568,7 +566,7 @@ discussions there. Django's online documentation also includes pointers on how to contribute to Django: - * :ref:`How to contribute to Django <internals-contributing>` + * :doc:`How to contribute to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed bugfixes -- are always welcome and diff --git a/docs/releases/1.2-beta-1.txt b/docs/releases/1.2-beta-1.txt index 650971de2b..2a12ef33bb 100644 --- a/docs/releases/1.2-beta-1.txt +++ b/docs/releases/1.2-beta-1.txt @@ -1,5 +1,3 @@ -.. _releases-1.2-beta-1: - =============================== Django 1.2 beta 1 release notes =============================== @@ -19,7 +17,7 @@ As such, this release is *not* intended for production use, and any such use is discouraged. This document covers changes since the Django 1.2 alpha release; the -:ref:`1.2 alpha release notes <releases-1.2-alpha-1>` cover new and +:doc:`1.2 alpha release notes </releases/1.2-alpha-1>` cover new and updated features in Django between 1.1 and 1.2 alpha. @@ -28,7 +26,7 @@ Deprecations and other changes in 1.2 beta This beta release deprecates two portions of public API, and introduces a potentially backwards-incompatible change to -another. Under :ref:`our API stability policy <misc-api-stability>`, +another. Under :doc:`our API stability policy </misc/api-stability>`, deprecation proceeds over multiple release cycles: initially, the deprecated API will raise ``PendingDeprecationWarning``, followed by raising ``DeprecationWarning`` in the next release, and finally @@ -58,8 +56,8 @@ Also, in accordance with `RSS best practices`_, RSS feeds will now include an ``atom:link`` element. You may need to update your tests to take this into account. -For more information, see the full :ref:`syndication framework -documentation <ref-contrib-syndication>`. +For more information, see the full :doc:`syndication framework +documentation </ref/contrib/syndication>`. .. _RSS best practices: http://www.rssboard.org/rss-profile @@ -93,7 +91,7 @@ added in Django 1.2 alpha but not documented with the alpha release. The default authentication backends shipped with Django do not currently make use of this, but third-party authentication backends -are free to do so. See the :ref:`authentication docs <topics-auth>` +are free to do so. See the :doc:`authentication docs </topics/auth>` for more information. @@ -106,7 +104,7 @@ class will check the backend for permissions, just as the normal ``User`` does. This is intended to help centralize permission handling; apps can always delegate the question of whether something is allowed or not to the authorization/authentication system. See the -:ref:`authentication docs <topics-auth>` for more details. +:doc:`authentication docs </topics/auth>` for more details. ``select_related()`` improvements @@ -163,7 +161,7 @@ discussions there. Django's online documentation also includes pointers on how to contribute to Django: - * :ref:`How to contribute to Django <internals-contributing>` + * :doc:`How to contribute to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed bugfixes -- diff --git a/docs/releases/1.2-rc-1.txt b/docs/releases/1.2-rc-1.txt index c627612a6e..b599dcca1e 100644 --- a/docs/releases/1.2-rc-1.txt +++ b/docs/releases/1.2-rc-1.txt @@ -1,5 +1,3 @@ -.. _releases-1.2-rc-1: - ============================= Django 1.2 RC 1 release notes ============================= @@ -21,8 +19,8 @@ such use is discouraged. Django has been feature frozen since the 1.2 beta release, so this release candidate contains no new features, only bugfixes; for a -summary of features new to Django 1.2, consult the :ref:`1.2 alpha -<releases-1.2-alpha-1>` and :ref:`1.2 beta <releases-1.2-beta-1>` +summary of features new to Django 1.2, consult the :doc:`1.2 alpha +</releases/1.2-alpha-1>` and :doc:`1.2 beta </releases/1.2-beta-1>` release notes. @@ -42,7 +40,7 @@ This change should affect only a small number of Django users, as most operating-system vendors today are shipping Python 2.4 or newer as their default version. If you're still using Python 2.3, however, you'll need to stick to Django 1.1 until you can upgrade; per -:ref:`our support policy <internals-release-process>`, Django 1.1 will +:doc:`our support policy </internals/release-process>`, Django 1.1 will continue to receive security support until the release of Django 1.3. A roadmap for Django's overall 2.x Python support, and eventual @@ -96,7 +94,7 @@ discussions there. Django's online documentation also includes pointers on how to contribute to Django: - * :ref:`How to contribute to Django <internals-contributing>` + * :doc:`How to contribute to Django </internals/contributing>` Contributions on any level -- developing code, writing documentation or simply triaging tickets and helping to test proposed bugfixes -- are always welcome and diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt index a54675514f..f46c19b8e8 100644 --- a/docs/releases/1.2.txt +++ b/docs/releases/1.2.txt @@ -1,5 +1,3 @@ -.. _releases-1.2: - ======================== Django 1.2 release notes ======================== @@ -21,11 +19,11 @@ Overview Django 1.2 introduces several large, important new features, including: * Support for `multiple database connections`_ in a single Django instance. - + * `Model validation`_ inspired by Django's form validation. - + * Vastly `improved protection against Cross-Site Request Forgery`_ (CSRF). - + * A new `user "messages" framework`_ with support for cookie- and session-based message for both anonymous and authenticated users. @@ -49,13 +47,13 @@ be found below`_. .. seealso:: - `Django Advent`_ covered the release of Django 1.2 with a series of + `Django Advent`_ covered the release of Django 1.2 with a series of articles and tutorials that cover some of the new features in depth. - + .. _django advent: http://djangoadvent.com/ Wherever possible these features have been introduced in a backwards-compatible -manner per :ref:`our API stability policy <misc-api-stability>` policy. +manner per :doc:`our API stability policy </misc/api-stability>` policy. However, a handful of features *have* changed in ways that, for some users, will be backwards-incompatible. The big changes are: @@ -66,7 +64,7 @@ backwards-incompatible. The big changes are: * The new CSRF protection framework is not backwards-compatible with the old system. Users of the old system will not be affected until the old system is removed in Django 1.4. - + However, upgrading to the new CSRF protection framework requires a few important backwards-incompatible changes, detailed in `CSRF Protection`_, below. @@ -74,12 +72,12 @@ backwards-incompatible. The big changes are: * Authors of custom :class:`~django.db.models.Field` subclasses should be aware that a number of methods have had a change in prototype, detailed under `get_db_prep_*() methods on Field`_, below. - + * The internals of template tags have changed somewhat; authors of custom template tags that need to store state (e.g. custom control flow tags) should ensure that their code follows the new rules for `stateful template tags`_ - + * The :func:`~django.contrib.auth.decorators.user_passes_test`, :func:`~django.contrib.auth.decorators.login_required`, and :func:`~django.contrib.auth.decorators.permission_required`, decorators @@ -110,7 +108,7 @@ This change should affect only a small number of Django users, as most operating-system vendors today are shipping Python 2.4 or newer as their default version. If you're still using Python 2.3, however, you'll need to stick to Django 1.1 until you can upgrade; per -:ref:`our support policy <internals-release-process>`, Django 1.1 will +:doc:`our support policy </internals/release-process>`, Django 1.1 will continue to receive security support until the release of Django 1.3. A roadmap for Django's overall 2.x Python support, and eventual @@ -123,8 +121,8 @@ What's new in Django 1.2 Support for multiple databases ------------------------------ -Django 1.2 adds the ability to use :ref:`more than one database -<topics-db-multi-db>` in your Django project. Queries can be issued at a +Django 1.2 adds the ability to use :doc:`more than one database +</topics/db/multi-db>` in your Django project. Queries can be issued at a specific database with the `using()` method on ``QuerySet`` objects. Individual objects can be saved to a specific database by providing a ``using`` argument when you call ``save()``. @@ -134,7 +132,7 @@ Model validation Model instances now have support for :ref:`validating their own data <validating-objects>`, and both model and form fields now accept configurable -lists of :ref:`validators <ref-validators>` specifying reusable, encapsulated +lists of :doc:`validators </ref/validators>` specifying reusable, encapsulated validation behavior. Note, however, that validation must still be performed explicitly. Simply invoking a model instance's ``save()`` method will not perform any validation of the instance's data. @@ -142,8 +140,8 @@ perform any validation of the instance's data. Improved CSRF protection ------------------------ -Django now has much improved protection against :ref:`Cross-Site Request Forgery -(CSRF) attacks<ref-contrib-csrf>`. This type of attack occurs when a malicious +Django now has much improved protection against :doc:`Cross-Site Request Forgery +(CSRF) attacks</ref/contrib/csrf>`. This type of attack occurs when a malicious Web site contains a link, a form button or some JavaScript that is intended to perform some action on your Web site, using the credentials of a logged-in user who visits the malicious site in their browser. A related type of attack, "login @@ -153,8 +151,8 @@ with someone else's credentials, is also covered. Messages framework ------------------ -Django now includes a robust and configurable :ref:`messages framework -<ref-contrib-messages>` with built-in support for cookie- and session-based +Django now includes a robust and configurable :doc:`messages framework +</ref/contrib/messages>` with built-in support for cookie- and session-based messaging, for both anonymous and authenticated clients. The messages framework replaces the deprecated user message API and allows you to temporarily store messages in one request and retrieve them for display in a subsequent request @@ -166,8 +164,8 @@ Object-level permissions A foundation for specifying permissions at the per-object level has been added. Although there is no implementation of this in core, a custom authentication backend can provide this implementation and it will be used by -:class:`django.contrib.auth.models.User`. See the :ref:`authentication docs -<topics-auth>` for more information. +:class:`django.contrib.auth.models.User`. See the :doc:`authentication docs +</topics/auth>` for more information. Permissions for anonymous users ------------------------------- @@ -176,8 +174,8 @@ If you provide a custom auth backend with ``supports_anonymous_user`` set to ``True``, AnonymousUser will check the backend for permissions, just like User already did. This is useful for centralizing permission handling - apps can always delegate the question of whether something is allowed or not to -the authorization/authentication backend. See the :ref:`authentication -docs <topics-auth>` for more details. +the authorization/authentication backend. See the :doc:`authentication +docs </topics/auth>` for more details. Relaxed requirements for usernames ---------------------------------- @@ -194,7 +192,7 @@ You can now :ref:`configure the way that Django sends e-mail can now choose a configurable e-mail backend to send messages. If your hosting provider uses a sandbox or some other non-SMTP technique for sending mail, you can now construct an e-mail backend that will allow -Django's standard :ref:`mail sending methods<topics-email>` to use +Django's standard :doc:`mail sending methods</topics/email>` to use those facilities. This also makes it easier to debug mail sending. Django ships with @@ -286,7 +284,7 @@ Models can now use a 64-bit :class:`~django.db.models.BigIntegerField` type. Improved localization --------------------- -Django's :ref:`internationalization framework <topics-i18n>` has been expanded +Django's :doc:`internationalization framework </topics/i18n/index>` has been expanded with locale-aware formatting and form processing. That means, if enabled, dates and numbers on templates will be displayed using the format specified for the current locale. Django will also use localized formats when parsing data in @@ -309,8 +307,8 @@ the colors used by ``django-admin.py`` to provide :ref:`syntax highlighting Syndication feeds as views -------------------------- -:ref:`Syndication feeds <ref-contrib-syndication>` can now be used directly as -views in your :ref:`URLconf <topics-http-urls>`. This means that you can +:doc:`Syndication feeds </ref/contrib/syndication>` can now be used directly as +views in your :doc:`URLconf </topics/http/urls>`. This means that you can maintain complete control over the URL structure of your feeds. Like any other view, feeds views are passed a ``request`` object, so you can do anything you would normally do with a view, like user based access control, or making a feed @@ -319,7 +317,7 @@ a named URL. GeoDjango --------- -The most significant new feature for :ref:`GeoDjango <ref-contrib-gis>` +The most significant new feature for :doc:`GeoDjango </ref/contrib/gis/index>` in 1.2 is support for multiple spatial databases. As a result, the following :ref:`spatial database backends <spatial-backends>` are now included: @@ -357,7 +355,7 @@ set a :attr:`~django.contrib.gis.gdal.Layer.spatial_filter` on the features returned when iterating over a :class:`~django.contrib.gis.gdal.Layer`. -Finally, :ref:`GeoDjango's documentation <ref-contrib-gis>` is now +Finally, :doc:`GeoDjango's documentation </ref/contrib/gis/index>` is now included with Django's and is no longer hosted separately at `geodjango.org <http://geodjango.org/>`_. @@ -391,8 +389,8 @@ Backwards-incompatible changes in 1.2 ===================================== Wherever possible the new features above have been introduced in a -backwards-compatible manner per :ref:`our API stability policy -<misc-api-stability>` policy. This means that practically all existing +backwards-compatible manner per :doc:`our API stability policy +</misc/api-stability>` policy. This means that practically all existing code which worked with Django 1.1 will continue to work with Django 1.2; such code will, however, begin issuing warnings (see below for details). @@ -405,7 +403,7 @@ CSRF Protection --------------- We've made large changes to the way CSRF protection works, detailed in -:ref:`the CSRF documentaton <ref-contrib-csrf>`. Here are the major changes you +:doc:`the CSRF documentaton </ref/contrib/csrf>`. Here are the major changes you should be aware of: * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated and @@ -435,6 +433,8 @@ database-compatible values. A custom field might look something like:: class CustomModelField(models.Field): # ... + def db_type(self): + # ... def get_db_prep_save(self, value): # ... @@ -451,6 +451,9 @@ two extra methods have been introduced:: class CustomModelField(models.Field): # ... + def db_type(self, connection): + # ... + def get_prep_value(self, value): # ... @@ -467,10 +470,10 @@ two extra methods have been introduced:: # ... These changes are required to support multiple databases -- -``get_db_prep_*`` can no longer make any assumptions regarding the -database for which it is preparing. The ``connection`` argument now -provides the preparation methods with the specific connection for -which the value is being prepared. +``db_type`` and ``get_db_prep_*`` can no longer make any assumptions +regarding the database for which it is preparing. The ``connection`` +argument now provides the preparation methods with the specific +connection for which the value is being prepared. The two new methods exist to differentiate general data-preparation requirements from requirements that are database-specific. The @@ -603,13 +606,13 @@ new keyword and so is not a valid variable name in this tag. -------------- ``LazyObject`` is an undocumented-but-often-used utility class used for lazily -wrapping other objects of unknown type. +wrapping other objects of unknown type. In Django 1.1 and earlier, it handled introspection in a non-standard way, depending on wrapped objects implementing a public method named ``get_all_members()``. Since this could easily lead to name clashes, it has been changed to use the standard Python introspection method, involving -``__members__`` and ``__dir__()``. +``__members__`` and ``__dir__()``. If you used ``LazyObject`` in your own code and implemented the ``get_all_members()`` method for wrapped objects, you'll need @@ -737,9 +740,9 @@ be removed entirely. .. seealso:: - For more details, see the documentation :ref:`Django's release process - <internals-release-process>` and our :ref:`deprecation timeline - <internals-deprecation>`.` + For more details, see the documentation :doc:`Django's release process + </internals/release-process>` and our :doc:`deprecation timeline + </internals/deprecation>`.` .. _specifying-databases: @@ -872,7 +875,7 @@ User Messages API The API for storing messages in the user ``Message`` model (via ``user.message_set.create``) is now deprecated and will be removed in Django -1.4 according to the standard :ref:`release process <internals-release-process>`. +1.4 according to the standard :doc:`release process </internals/release-process>`. To upgrade your code, you need to replace any instances of this:: @@ -896,7 +899,7 @@ following:: ... For more information, see the full -:ref:`messages documentation <ref-contrib-messages>`. You should begin to +:doc:`messages documentation </ref/contrib/messages>`. You should begin to update your code to use the new API immediately. Date format helper functions @@ -960,7 +963,7 @@ Django 1.4. The new class has an almost identical API, but allows instances to be used as views. For example, consider the use of the old framework in -the following :ref:`URLconf <topics-http-urls>`:: +the following :doc:`URLconf </topics/http/urls>`:: from django.conf.urls.defaults import * from myproject.feeds import LatestEntries, LatestEntriesByCategory @@ -1029,8 +1032,8 @@ In accordance with `RSS best practices`_, RSS feeds will now include an ``atom:link`` element. You may need to update your tests to take this into account. -For more information, see the full :ref:`syndication framework -documentation <ref-contrib-syndication>`. +For more information, see the full :doc:`syndication framework +documentation </ref/contrib/syndication>`. .. _RSS best practices: http://www.rssboard.org/rss-profile diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt new file mode 100644 index 0000000000..51de6fdd92 --- /dev/null +++ b/docs/releases/1.3.txt @@ -0,0 +1,86 @@ +============================================ +Django 1.3 release notes - UNDER DEVELOPMENT +============================================ + +This page documents release notes for the as-yet-unreleased Django +1.3. As such, it's tentative and subject to change. It provides +up-to-date information for those who are following trunk. + +Django 1.3 includes a number of nifty `new features`_, lots of bug +fixes and an easy upgrade path from Django 1.2. + +.. _new features: `What's new in Django 1.3`_ + +.. _backwards-incompatible-changes-1.3: + +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)) + +.. _deprecated-features-1.3: + +Features deprecated in 1.3 +========================== + +Django 1.3 deprecates some features from earlier releases. +These features are still supported, but will be gradually phased out +over the next few release cycles. + +Code taking advantage of any of the features below will raise a +``PendingDeprecationWarning`` in Django 1.3. This warning will be +silent by default, but may be turned on using Python's `warnings +module`_, or by running Python with a ``-Wd`` or `-Wall` flag. + +.. _warnings module: http://docs.python.org/library/warnings.html + +In Django 1.4, these warnings will become a ``DeprecationWarning``, +which is *not* silent. In Django 1.5 support for these features will +be removed entirely. + +.. seealso:: + + For more details, see the documentation :doc:`Django's release process + </internals/release-process>` and our :doc:`deprecation timeline + </internals/deprecation>`.` + +``mod_python`` support +~~~~~~~~~~~~~~~~~~~~~~ + +The ``mod_python`` library has not had a release since 2007 or a commit since +2008. The Apache Foundation board voted to remove ``mod_python`` from the set +of active projects in its version control repositories, and its lead developer +has shifted all of his efforts toward the lighter, slimmer, more stable, and +more flexible ``mod_wsgi`` backend. + +If you are currently using the ``mod_python`` request handler, it is strongly +encouraged you redeploy your Django instances using :doc:`mod_wsgi +</howto/deployment/modwsgi>`. + +What's new in Django 1.3 +======================== + diff --git a/docs/releases/index.txt b/docs/releases/index.txt index 676ee67519..aa014f3cf2 100644 --- a/docs/releases/index.txt +++ b/docs/releases/index.txt @@ -1,5 +1,3 @@ -.. _releases-index: - ============= Release notes ============= @@ -16,6 +14,13 @@ up to and including the new version. Final releases ============== +1.3 release +----------- +.. toctree:: + :maxdepth: 1 + + 1.3 + 1.2 release ----------- .. toctree:: diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt index 4e07f73190..8c9b0f1cff 100644 --- a/docs/topics/auth.txt +++ b/docs/topics/auth.txt @@ -1,5 +1,3 @@ -.. _topics-auth: - ============================= User authentication in Django ============================= @@ -138,8 +136,8 @@ Methods :class:`~django.contrib.auth.models.User` objects have two many-to-many fields: models.User. ``groups`` and ``user_permissions``. :class:`~django.contrib.auth.models.User` objects can access their related - objects in the same way as any other :ref:`Django model - <topics-db-models>`: + objects in the same way as any other :doc:`Django model + </topics/db/models>`: .. code-block:: python @@ -435,8 +433,6 @@ Anonymous users instead of ``False``. * :meth:`~django.contrib.auth.models.User.is_authenticated()` returns ``False`` instead of ``True``. - * :meth:`~django.contrib.auth.models.User.has_perm()` always returns - ``False``. * :meth:`~django.contrib.auth.models.User.set_password()`, :meth:`~django.contrib.auth.models.User.check_password()`, :meth:`~django.contrib.auth.models.User.save()`, @@ -539,7 +535,7 @@ First, install the :class:`~django.contrib.sessions.middleware.SessionMiddleware` and :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` middlewares by adding them to your :setting:`MIDDLEWARE_CLASSES` setting. See -the :ref:`session documentation <topics-http-sessions>` for more information. +the :doc:`session documentation </topics/http/sessions>` for more information. Once you have those middlewares installed, you'll be able to access :attr:`request.user <django.http.HttpRequest.user>` in views. @@ -556,7 +552,7 @@ section). You can tell them apart with else: # Do something for anonymous users. -.. _howtologauserin: +.. _how-to-log-a-user-in: How to log a user in -------------------- @@ -717,6 +713,17 @@ The login_required decorator def my_view(request): ... + .. versionadded:: 1.3 + + :func:`~django.contrib.auth.decorators.login_required` also takes an + optional ``login_url`` parameter. Example:: + + from django.contrib.auth.decorators import login_required + + @login_required(login_url='/accounts/login/') + def my_view(request): + ... + :func:`~django.contrib.auth.decorators.login_required` does the following: * If the user isn't logged in, redirect to @@ -730,9 +737,9 @@ The login_required decorator * If the user is logged in, execute the view normally. The view code is free to assume the user is logged in. -Note that you'll need to map the appropriate Django view to -:setting:`settings.LOGIN_URL <LOGIN_URL>`. For example, using the defaults, add -the following line to your URLconf:: +Note that if you don't specify the ``login_url`` parameter, you'll need to map +the appropriate Django view to :setting:`settings.LOGIN_URL <LOGIN_URL>`. For +example, using the defaults, add the following line to your URLconf:: (r'^accounts/login/$', 'django.contrib.auth.views.login'), @@ -755,7 +762,7 @@ the following line to your URLconf:: template context variables: * ``form``: A :class:`~django.forms.Form` object representing the login - form. See the :ref:`forms documentation <topics-forms-index>` for + form. See the :doc:`forms documentation </topics/forms/index>` for more on ``Form`` objects. * ``next``: The URL to redirect to after successful login. This may @@ -771,7 +778,7 @@ the following line to your URLconf:: * ``site_name``: An alias for ``site.name``. If you don't have the site framework installed, this will be set to the value of :attr:`request.META['SERVER_NAME'] <django.http.HttpRequest.META>`. - For more on sites, see :ref:`ref-contrib-sites`. + For more on sites, see :doc:`/ref/contrib/sites`. If you'd prefer not to call the template :file:`registration/login.html`, you can pass the ``template_name`` parameter via the extra arguments to @@ -798,7 +805,8 @@ the following line to your URLconf:: <p>Your username and password didn't match. Please try again.</p> {% endif %} - <form method="post" action="{% url django.contrib.auth.views.login %}">{% csrf_token %} + <form method="post" action="{% url django.contrib.auth.views.login %}"> + {% csrf_token %} <table> <tr> <td>{{ form.username.label_tag }}</td> @@ -898,10 +906,11 @@ includes a few other useful built-in views located in default to :file:`registration/password_change_done.html` if not supplied. -.. function:: views.password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect]) +.. function:: views.password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email]) - 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:** @@ -923,6 +932,11 @@ includes a few other useful built-in views located in * ``post_reset_redirect``: The URL to redirect to after a successful password change. + .. versionchanged:: 1.3 + + * ``from_email``: A valid e-mail address. By default Django uses + the :setting:`DEFAULT_FROM_EMAIL`. + **Template context:** * ``form``: The form for resetting the user's password. @@ -1007,8 +1021,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 @@ -1112,7 +1126,7 @@ The permission_required decorator Limiting access to generic views -------------------------------- -To limit access to a :ref:`generic view <ref-generic-views>`, write a thin +To limit access to a :doc:`generic view </ref/generic-views>`, write a thin wrapper around the view, and point your URLconf to your wrapper instead of the generic view itself. For example:: @@ -1229,13 +1243,13 @@ Methods ~~~~~~~ :class:`~django.contrib.auth.models.Permission` objects have the standard -data-access methods like any other :ref:`Django model <ref-models-instances>`. +data-access methods like any other :doc:`Django model </ref/models/instances>`. Authentication data in templates ================================ The currently logged-in user and his/her permissions are made available in the -:ref:`template context <ref-templates-api>` when you use +:doc:`template context </ref/templates/api>` when you use :class:`~django.template.context.RequestContext`. .. admonition:: Technicality @@ -1324,7 +1338,7 @@ Messages .. deprecated:: 1.2 This functionality will be removed in Django 1.4. You should use the - :ref:`messages framework <ref-contrib-messages>` for all new projects and + :doc:`messages framework </ref/contrib/messages>` for all new projects and begin to update your existing code immediately. The message system is a lightweight way to queue messages for given users. @@ -1359,7 +1373,7 @@ a playlist:: When you use :class:`~django.template.context.RequestContext`, the currently logged-in user and his/her messages are made available in the -:ref:`template context <ref-templates-api>` as the template variable +:doc:`template context </ref/templates/api>` as the template variable ``{{ messages }}``. Here's an example of template code that displays messages: .. code-block:: html+django @@ -1374,14 +1388,14 @@ logged-in user and his/her messages are made available in the .. versionchanged:: 1.2 The ``messages`` template variable uses a backwards compatible method in the - :ref:`messages framework <ref-contrib-messages>` to retrieve messages from + :doc:`messages framework </ref/contrib/messages>` to retrieve messages from both the user ``Message`` model and from the new framework. Unlike in previous revisions, the messages will not be erased unless they are actually displayed. Finally, note that this messages framework only works with users in the user database. To send messages to anonymous users, use the -:ref:`messages framework <ref-contrib-messages>`. +:doc:`messages framework </ref/contrib/messages>`. .. _authentication-backends: @@ -1402,7 +1416,7 @@ plug in other authentication sources. You can override Django's default database-based scheme, or you can use the default system in tandem with other systems. -See the :ref:`authentication backend reference <ref-authentication-backends>` +See the :doc:`authentication backend reference </ref/authbackends>` for information on the authentication backends included with Django. Specifying authentication backends @@ -1411,9 +1425,9 @@ Specifying authentication backends Behind the scenes, Django maintains a list of "authentication backends" that it checks for authentication. When somebody calls :func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log -a user in` above -- Django tries authenticating across all of its -authentication backends. If the first authentication method fails, Django tries -the second one, and so on, until all backends have been attempted. +a user in <how-to-log-a-user-in>` above -- Django tries authenticating across +all of its authentication backends. If the first authentication method fails, +Django tries the second one, and so on, until all backends have been attempted. The list of authentication backends to use is specified in the :setting:`AUTHENTICATION_BACKENDS` setting. This should be a tuple of Python @@ -1593,7 +1607,7 @@ object permissions will always return ``False`` or an empty list (depending on the check performed). To enable object permissions in your own -:ref:`authentication backend <ref-authentication-backends>` you'll just have +:doc:`authentication backend </ref/authbackends>` you'll just have to allow passing an ``obj`` parameter to the permission methods and set the ``supports_object_permissions`` class attribute to ``True``. diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index 9dedbcf3b9..5797199411 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -1,5 +1,3 @@ -.. _topics-cache: - ======================== Django's cache framework ======================== @@ -136,6 +134,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 ------------------ @@ -301,7 +342,7 @@ Additionally, the cache middleware automatically sets a few headers in each * Sets the ``Cache-Control`` header to give a max age for the page -- again, from the ``CACHE_MIDDLEWARE_SECONDS`` setting. -See :ref:`topics-http-middleware` for more on middleware. +See :doc:`/topics/http/middleware` for more on middleware. .. versionadded:: 1.0 @@ -322,7 +363,7 @@ include the name of the active :term:`language<language code>`. This allows you to easily cache multilingual sites without having to create the cache key yourself. -See :ref:`topics-i18n-deployment` for more on how Django discovers the active +See :doc:`/topics/i18n/deployment` for more on how Django discovers the active language. __ `Controlling cache: Using other headers`_ @@ -600,6 +641,45 @@ nonexistent cache key.:: However, if the backend doesn't natively provide an increment/decrement operation, it will be implemented using a two-step retrieve/update. +Cache key warnings +------------------ + +.. versionadded:: 1.3 + +Memcached, the most commonly-used production cache backend, does not allow +cache keys longer than 250 characters or containing whitespace or control +characters, and using such keys will cause an exception. To encourage +cache-portable code and minimize unpleasant surprises, the other built-in cache +backends issue a warning (``django.core.cache.backends.base.CacheKeyWarning``) +if a key is used that would cause an error on memcached. + +If you are using a production backend that can accept a wider range of keys (a +custom backend, or one of the non-memcached built-in backends), and want to use +this wider range without warnings, you can silence ``CacheKeyWarning`` with +this code in the ``management`` module of one of your +:setting:`INSTALLED_APPS`:: + + import warnings + + from django.core.cache import CacheKeyWarning + + warnings.simplefilter("ignore", CacheKeyWarning) + +If you want to instead provide custom key validation logic for one of the +built-in backends, you can subclass it, override just the ``validate_key`` +method, and follow the instructions for `using a custom cache backend`_. For +instance, to do this for the ``locmem`` backend, put this code in a module:: + + from django.core.cache.backends.locmem import CacheClass as LocMemCacheClass + + class CacheClass(LocMemCacheClass): + def validate_key(self, key): + """Custom validation, raising exceptions or warnings as needed.""" + # ... + +...and use the dotted Python path to this module as the scheme portion of your +:setting:`CACHE_BACKEND`. + Upstream caches =============== diff --git a/docs/topics/conditional-view-processing.txt b/docs/topics/conditional-view-processing.txt index 1ce3c3bb92..b5da140827 100644 --- a/docs/topics/conditional-view-processing.txt +++ b/docs/topics/conditional-view-processing.txt @@ -1,5 +1,3 @@ -.. _topics-conditional-processing: - =========================== Conditional View Processing =========================== diff --git a/docs/topics/db/aggregation.txt b/docs/topics/db/aggregation.txt index 087c1bf239..eb21021038 100644 --- a/docs/topics/db/aggregation.txt +++ b/docs/topics/db/aggregation.txt @@ -1,5 +1,3 @@ -.. _topics-db-aggregation: - =========== Aggregation =========== @@ -8,7 +6,7 @@ Aggregation .. currentmodule:: django.db.models -The topic guide on :ref:`Django's database-abstraction API <topics-db-queries>` +The topic guide on :doc:`Django's database-abstraction API </topics/db/queries>` described the way that you can use Django queries that create, retrieve, update and delete individual objects. However, sometimes you will need to retrieve values that are derived by summarizing or *aggregating* a @@ -353,7 +351,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. @@ -363,7 +361,7 @@ you also select in a ``values()`` call. for you. The main reason is consistency with ``distinct()`` and other places: Django **never** removes ordering constraints that you have specified (and we can't change those other methods' behavior, as that - would violate our :ref:`misc-api-stability` policy). + would violate our :doc:`/misc/api-stability` policy). Aggregating annotations ----------------------- diff --git a/docs/topics/db/index.txt b/docs/topics/db/index.txt index 3eb62b70ca..c49f158e64 100644 --- a/docs/topics/db/index.txt +++ b/docs/topics/db/index.txt @@ -1,5 +1,3 @@ -.. _topics-db-index: - Models and databases ==================== diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt index 123408b2bb..5ebe0b1b94 100644 --- a/docs/topics/db/managers.txt +++ b/docs/topics/db/managers.txt @@ -1,5 +1,3 @@ -.. _topics-db-managers: - ======== Managers ======== @@ -12,7 +10,7 @@ A ``Manager`` is the interface through which database query operations are provided to Django models. At least one ``Manager`` exists for every model in a Django application. -The way ``Manager`` classes work is documented in :ref:`topics-db-queries`; +The way ``Manager`` classes work is documented in :doc:`/topics/db/queries`; this document specifically touches on model options that customize ``Manager`` behavior. @@ -170,7 +168,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 @@ -324,7 +323,7 @@ it will use :class:`django.db.models.Manager`. attribute only controlled the type of manager used for related field access, which is where the name came from. As it became clear the concept was more broadly useful, the name hasn't been changed. This is primarily - so that existing code will :ref:`continue to work <misc-api-stability>` in + so that existing code will :doc:`continue to work </misc/api-stability>` in future Django versions. Writing Correct Managers For Use In Automatic Manager Instances diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 6d7a7a4374..0ff34ea0e1 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -1,5 +1,3 @@ -.. _topics-db-models: - ====== Models ====== @@ -18,7 +16,7 @@ The basics: * Each attribute of the model represents a database field. * With all of this, Django gives you an automatically-generated - database-access API; see :ref:`topics-db-queries`. + database-access API; see :doc:`/topics/db/queries`. .. seealso:: @@ -64,7 +62,7 @@ Some technical notes: * The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL syntax, but it's worth noting Django uses SQL tailored to the database - backend specified in your :ref:`settings file <topics-settings>`. + backend specified in your :doc:`settings file </topics/settings>`. Using models ============ @@ -126,7 +124,7 @@ determine a few things: Django ships with dozens of built-in field types; you can find the complete list in the :ref:`model field reference <model-field-types>`. You can easily write your own fields if Django's built-in ones don't do the trick; see -:ref:`howto-custom-model-fields`. +:doc:`/howto/custom-model-fields`. Field options ------------- @@ -353,7 +351,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. @@ -612,7 +610,7 @@ Custom field types If one of the existing model fields cannot be used to fit your purposes, or if you wish to take advantage of some less common database column types, you can create your own field class. Full coverage of creating your own fields is -provided in :ref:`howto-custom-model-fields`. +provided in :doc:`/howto/custom-model-fields`. .. _meta-options: @@ -634,8 +632,8 @@ human-readable singular and plural names (:attr:`~Options.verbose_name` and :attr:`~Options.verbose_name_plural`). None are required, and adding ``class Meta`` to a model is completely optional. -A complete list of all possible ``Meta`` options can be found in the :ref:`model -option reference <ref-models-options>`. +A complete list of all possible ``Meta`` options can be found in the :doc:`model +option reference </ref/models/options>`. .. _model-methods: @@ -684,7 +682,7 @@ properties`_. .. _Read more about properties: http://www.python.org/download/releases/2.2/descrintro/#property -The :ref:`model instance reference <ref-models-instances>` has a complete list +The :doc:`model instance reference </ref/models/instances>` has a complete list of :ref:`methods automatically given to each model <model-instance-methods>`. You can override most of these -- see `overriding predefined model methods`_, below -- but there are a couple that you'll almost always want to define: @@ -763,7 +761,7 @@ Executing custom SQL Another common pattern is writing custom SQL statements in model methods and module-level methods. For more details on using raw SQL, see the documentation -on :ref:`using raw SQL<topics-db-sql>`. +on :doc:`using raw SQL</topics/db/sql>`. .. _model-inheritance: diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt index e3f62ea71b..1a939b0e3a 100644 --- a/docs/topics/db/multi-db.txt +++ b/docs/topics/db/multi-db.txt @@ -1,5 +1,3 @@ -.. _topics-db-multi-db: - ================== Multiple databases ================== @@ -240,7 +238,7 @@ master/slave relationship between the databases ``master``, ``slave1`` and return False return None - class MasterSlaveRouter(object): + class MasterSlaveRouter(object): """A router that sets up a simple master/slave configuration""" def db_for_read(self, model, **hints): diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index 6063bc6c2a..baf8cfa268 100644 --- a/docs/topics/db/optimization.txt +++ b/docs/topics/db/optimization.txt @@ -1,11 +1,9 @@ -.. _topics-db-optimization: - ============================ Database access optimization ============================ Django's database layer provides various ways to help developers get the most -out of their databases. This documents gathers together links to the relevant +out of their databases. This document gathers together links to the relevant documentation, and adds various tips, organized under an number of headings that outline the steps to take when attempting to optimize your database usage. @@ -45,13 +43,13 @@ Use standard DB optimization techniques We will assume you have done the obvious things above. The rest of this document focuses on how to use Django in such a way that you are not doing unnecessary work. This document also does not address other optimization techniques that -apply to all expensive operations, such as :ref:`general purpose caching -<topics-cache>`. +apply to all expensive operations, such as :doc:`general purpose caching +</topics/cache>`. Understand QuerySets ==================== -Understanding :ref:`QuerySets <ref-models-querysets>` is vital to getting good +Understanding :doc:`QuerySets </ref/models/querysets>` is vital to getting good performance with simple code. In particular: Understand QuerySet evaluation @@ -101,36 +99,35 @@ 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 ====================================================== For instance: -* At the most basic level, use :ref:`filter and exclude <queryset-api>` to - filtering in the database to avoid loading data into your Python process, only - to throw much of it away. +* At the most basic level, use :ref:`filter and exclude <queryset-api>` to do + filtering in the database. * Use :ref:`F() object query expressions <query-expressions>` to do filtering against other fields within the same model. -* Use :ref:`annotate to do aggregation in the database <topics-db-aggregation>`. +* Use :doc:`annotate to do aggregation in the database </topics/db/aggregation>`. 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 ----------- -Write your own :ref:`custom SQL to retrieve data or populate models -<topics-db-sql>`. Use ``django.db.connection.queries`` to find out what Django +Write your own :doc:`custom SQL to retrieve data or populate models +</topics/db/sql>`. Use ``django.db.connection.queries`` to find out what Django is writing for you and start from there. Retrieve everything at once if you know you will need it @@ -149,7 +146,7 @@ Understand :ref:`QuerySet.select_related() <select-related>` thoroughly, and use * in view code, -* and in :ref:`managers and default managers <topics-db-managers>` where +* and in :doc:`managers and default managers </topics/db/managers>` where appropriate. Be aware when your manager is and is not used; sometimes this is tricky so don't make assumptions. @@ -160,7 +157,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. @@ -168,7 +165,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. @@ -243,10 +241,7 @@ individual, use a bulk SQL UPDATE statement, via :ref:`QuerySet.update() Note, however, that these bulk update methods cannot call the ``save()`` or ``delete()`` methods of individual instances, which means that any custom behaviour you have added for these methods will not be executed, including anything driven from the -normal database object :ref:`signals <ref-signals>`. - -Don't retrieve things you already have -====================================== +normal database object :doc:`signals </ref/signals>`. Use foreign key values directly ------------------------------- diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 981d727f4f..b0d053c2e9 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -1,15 +1,13 @@ -.. _topics-db-queries: - ============== Making queries ============== .. currentmodule:: django.db.models -Once you've created your :ref:`data models <topics-db-models>`, Django +Once you've created your :doc:`data models </topics/db/models>`, Django automatically gives you a database-abstraction API that lets you create, retrieve, update and delete objects. This document explains how to use this -API. Refer to the :ref:`data model reference <ref-models-index>` for full +API. Refer to the :doc:`data model reference </ref/models/index>` for full details of all the various model lookup options. Throughout this guide (and in the reference), we'll refer to the following @@ -825,6 +823,8 @@ a join with an ``F()`` object, a ``FieldError`` will be raised:: # THIS WILL RAISE A FieldError >>> Entry.objects.update(headline=F('blog__name')) +.. _topics-db-queries-related: + Related objects =============== @@ -937,7 +937,7 @@ be accessed from an instance:: In addition to the ``QuerySet`` methods defined in "Retrieving objects" above, the ``ForeignKey`` ``Manager`` has additional methods used to handle the set of related objects. A synopsis of each is below, and complete details can be found -in the :ref:`related objects reference <ref-models-relations>`. +in the :doc:`related objects reference </ref/models/relations>`. ``add(obj1, obj2, ...)`` Adds the specified model objects to the related object set. @@ -1067,7 +1067,7 @@ Falling back to raw SQL If you find yourself needing to write an SQL query that is too complex for Django's database-mapper to handle, you can fall back on writing SQL by hand. Django has a couple of options for writing raw SQL queries; see -:ref:`topics-db-sql`. +:doc:`/topics/db/sql`. Finally, it's important to note that the Django database layer is merely an interface to your database. You can access your database via other tools, diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt index f55a164373..9f2be7a2ef 100644 --- a/docs/topics/db/sql.txt +++ b/docs/topics/db/sql.txt @@ -1,12 +1,10 @@ -.. _topics-db-sql: - ========================== Performing raw SQL queries ========================== .. currentmodule:: django.db.models -When the :ref:`model query APIs <topics-db-queries>` don't go far enough, you +When the :doc:`model query APIs </topics/db/queries>` don't go far enough, you can fall back to writing raw SQL. Django gives you two ways of performing raw SQL queries: you can use :meth:`Manager.raw()` to `perform raw queries and return model instances`__, or you can avoid the model layer entirely and @@ -116,9 +114,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 @@ -269,7 +267,7 @@ Connections and cursors ----------------------- ``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_ -(except when it comes to :ref:`transaction handling <topics-db-transactions>`). +(except when it comes to :doc:`transaction handling </topics/db/transactions>`). If you're not familiar with the Python DB-API, note that the SQL statement in ``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters directly within the SQL. If you use this technique, the underlying database diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index fb6e3f8646..2d99c17a32 100644 --- a/docs/topics/db/transactions.txt +++ b/docs/topics/db/transactions.txt @@ -1,5 +1,3 @@ -.. _topics-db-transactions: - ============================== Managing database transactions ============================== @@ -306,7 +304,7 @@ Database-level autocommit .. versionadded:: 1.1 With PostgreSQL 8.2 or later, there is an advanced option to run PostgreSQL -with :ref:`database-level autocommit <ref-databases>`. If you use this option, +with :doc:`database-level autocommit </ref/databases>`. If you use this option, there is no constantly open transaction, so it is always possible to continue after catching an exception. For example:: diff --git a/docs/topics/email.txt b/docs/topics/email.txt index 74e153de61..31092b0aaa 100644 --- a/docs/topics/email.txt +++ b/docs/topics/email.txt @@ -1,5 +1,3 @@ -.. _topics-email: - ============== Sending e-mail ============== @@ -501,7 +499,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/files.txt b/docs/topics/files.txt index 45aca5488a..26114cb50b 100644 --- a/docs/topics/files.txt +++ b/docs/topics/files.txt @@ -1,5 +1,3 @@ -.. _topics-files: - ============== Managing files ============== @@ -70,7 +68,7 @@ using a Python built-in ``file`` object:: >>> myfile = File(f) Now you can use any of the ``File`` attributes and methods documented in -:ref:`ref-files-file`. +:doc:`/ref/files/file`. File storage ============ @@ -84,7 +82,7 @@ setting; if you don't explicitly provide a storage system, this is the one that will be used. See below for details of the built-in default file storage system, and see -:ref:`howto-custom-file-storage` for information on writing your own file +:doc:`/howto/custom-file-storage` for information on writing your own file storage system. Storage objects @@ -111,7 +109,7 @@ useful -- you can use the global default storage system:: >>> default_storage.exists(path) False -See :ref:`ref-files-storage` for the file storage API. +See :doc:`/ref/files/storage` for the file storage API. The built-in filesystem storage class ------------------------------------- @@ -143,5 +141,5 @@ For example, the following code will store uploaded files under ... photo = models.ImageField(storage=fs) -:ref:`Custom storage systems <howto-custom-file-storage>` work the same way: you +:doc:`Custom storage systems </howto/custom-file-storage>` work the same way: you can pass them in as the ``storage`` argument to a ``FileField``. diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt index 732fd93de1..e7b09dc409 100644 --- a/docs/topics/forms/formsets.txt +++ b/docs/topics/forms/formsets.txt @@ -1,4 +1,3 @@ -.. _topics-forms-formsets: .. _formsets: Formsets diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 119e943889..cef322a02f 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -1,5 +1,3 @@ -.. _topics-forms-index: - ================== Working with forms ================== @@ -7,8 +5,8 @@ Working with forms .. admonition:: About this document This document provides an introduction to Django's form handling features. - For a more detailed look at the forms API, see :ref:`ref-forms-api`. For - documentation of the available field types, see :ref:`ref-forms-fields`. + For a more detailed look at the forms API, see :doc:`/ref/forms/api`. For + documentation of the available field types, see :doc:`/ref/forms/fields`. .. highlightlang:: html+django @@ -77,10 +75,10 @@ personal Web site: A form is composed of ``Field`` objects. In this case, our form has four fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. ``CharField``, ``EmailField`` and ``BooleanField`` are just three of the available field types; -a full list can be found in :ref:`ref-forms-fields`. +a full list can be found in :doc:`/ref/forms/fields`. If your form is going to be used to directly add or edit a Django model, you can -use a :ref:`ModelForm <topics-forms-modelforms>` to avoid duplicating your model +use a :doc:`ModelForm </topics/forms/modelforms>` to avoid duplicating your model description. Using a form in a view @@ -163,7 +161,7 @@ Extending the above example, here's how the form data could be processed: send_mail(subject, message, sender, recipients) return HttpResponseRedirect('/thanks/') # Redirect after POST -For more on sending e-mail from Django, see :ref:`topics-email`. +For more on sending e-mail from Django, see :doc:`/topics/email`. Displaying a form using a template ---------------------------------- @@ -397,4 +395,4 @@ This covers the basics, but forms can do a whole lot more: .. seealso:: - The :ref:`form API reference <ref-forms-index>`. + The :doc:`form API reference </ref/forms/index>`. diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt index 663b0d3113..64cf50743d 100644 --- a/docs/topics/forms/media.txt +++ b/docs/topics/forms/media.txt @@ -1,5 +1,3 @@ -.. _topics-forms-media: - Form Media ========== diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index fd3edf5104..2cdd2bfa74 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -1,5 +1,3 @@ -.. _topics-forms-modelforms: - ========================== Creating forms from models ========================== @@ -446,7 +444,7 @@ parameter when declaring the form field:: class Meta: model = Article - See the :ref:`form field documentation <ref-forms-fields>` for more information + See the :doc:`form field documentation </ref/forms/fields>` for more information on fields and their arguments. Changing the order of fields @@ -540,7 +538,7 @@ Interaction with model validation As part of its validation process, ``ModelForm`` will call the ``clean()`` method of each field on your model that has a corresponding field on your form. If you have excluded any model fields, validation will not be run on those -fields. See the :ref:`form validation <ref-forms-validation>` documentation +fields. See the :doc:`form validation </ref/forms/validation>` documentation for more on how field cleaning and validation work. Also, your model's ``clean()`` method will be called before any uniqueness checks are made. See :ref:`Validating objects <validating-objects>` for more information on the @@ -551,7 +549,7 @@ model's ``clean()`` hook. Model formsets ============== -Like :ref:`regular formsets <topics-forms-formsets>`, Django provides a couple +Like :doc:`regular formsets </topics/forms/formsets>`, Django provides a couple of enhanced formset classes that make it easy to work with Django models. Let's reuse the ``Author`` model from above:: @@ -595,8 +593,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/generic-views.txt b/docs/topics/generic-views.txt index f70bb43f38..f90745d451 100644 --- a/docs/topics/generic-views.txt +++ b/docs/topics/generic-views.txt @@ -1,5 +1,3 @@ -.. _topics-generic-views: - ============= Generic views ============= @@ -192,7 +190,7 @@ might look like the following:: That's really all there is to it. All the cool features of generic views come from changing the "info" dictionary passed to the generic view. The -:ref:`generic views reference<ref-generic-views>` documents all the generic +:doc:`generic views reference</ref/generic-views>` documents all the generic views and all their options in detail; the rest of this document will consider some of the common ways you might customize and extend generic views. @@ -315,9 +313,9 @@ Viewing subsets of objects Now let's take a closer look at this ``queryset`` key we've been using all along. Most generic views take one of these ``queryset`` arguments -- it's how -the view knows which set of objects to display (see :ref:`topics-db-queries` for +the view knows which set of objects to display (see :doc:`/topics/db/queries` for more information about ``QuerySet`` objects, and see the -:ref:`generic views reference<ref-generic-views>` for the complete details). +:doc:`generic views reference</ref/generic-views>` for the complete details). To pick a simple example, we might want to order a list of books by publication date, with the most recent first: @@ -365,7 +363,7 @@ We'll deal with this problem in the next section. If you get a 404 when requesting ``/books/acme/``, check to ensure you actually have a Publisher with the name 'ACME Publishing'. Generic views have an ``allow_empty`` parameter for this case. See the - :ref:`generic views reference<ref-generic-views>` for more details. + :doc:`generic views reference</ref/generic-views>` for more details. Complex filtering with wrapper functions ---------------------------------------- diff --git a/docs/topics/http/file-uploads.txt b/docs/topics/http/file-uploads.txt index ab8277599c..6b0a4d5722 100644 --- a/docs/topics/http/file-uploads.txt +++ b/docs/topics/http/file-uploads.txt @@ -1,5 +1,3 @@ -.. _topics-http-file-uploads: - ============ File Uploads ============ @@ -10,8 +8,8 @@ File Uploads When Django handles a file upload, the file data ends up placed in :attr:`request.FILES <django.http.HttpRequest.FILES>` (for more on the -``request`` object see the documentation for :ref:`request and response objects -<ref-request-response>`). This document explains how files are stored on disk +``request`` object see the documentation for :doc:`request and response objects +</ref/request-response>`). This document explains how files are stored on disk and in memory, and how to customize the default behavior. Basic file uploads diff --git a/docs/topics/http/generic-views.txt b/docs/topics/http/generic-views.txt index 5aa2c48ea5..15f895ea78 100644 --- a/docs/topics/http/generic-views.txt +++ b/docs/topics/http/generic-views.txt @@ -1,7 +1,5 @@ -.. _topics-http-generic-views: - ============= Generic views ============= -See :ref:`ref-generic-views`.
\ No newline at end of file +See :doc:`/ref/generic-views`. diff --git a/docs/topics/http/index.txt b/docs/topics/http/index.txt index ae73c2c29b..5ef776dd7b 100644 --- a/docs/topics/http/index.txt +++ b/docs/topics/http/index.txt @@ -1,5 +1,3 @@ -.. _topics-http-index: - Handling HTTP requests ====================== diff --git a/docs/topics/http/middleware.txt b/docs/topics/http/middleware.txt index 215a4ec12c..eee398a3dc 100644 --- a/docs/topics/http/middleware.txt +++ b/docs/topics/http/middleware.txt @@ -1,5 +1,3 @@ -.. _topics-http-middleware: - ========== Middleware ========== @@ -14,8 +12,8 @@ an ``"X-View"`` HTTP header to every response to a ``HEAD`` request. This document explains how middleware works, how you activate middleware, and how to write your own middleware. Django ships with some built-in middleware -you can use right out of the box; they're documented in the :ref:`built-in -middleware reference <ref-middleware>`. +you can use right out of the box; they're documented in the :doc:`built-in +middleware reference </ref/middleware>`. Activating middleware ===================== @@ -173,9 +171,9 @@ Guidelines cares about is that the :setting:`MIDDLEWARE_CLASSES` setting includes the path to it. - * Feel free to look at :ref:`Django's available middleware - <ref-middleware>` for examples. + * Feel free to look at :doc:`Django's available middleware + </ref/middleware>` for examples. * If you write a middleware component that you think would be useful to - other people, contribute to the community! :ref:`Let us know - <internals-contributing>`, and we'll consider adding it to Django. + other people, contribute to the community! :doc:`Let us know + </internals/contributing>`, and we'll consider adding it to Django. diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index 68ead03b65..8a0f0d4b72 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -1,5 +1,3 @@ -.. _topics-http-sessions: - =================== How to use sessions =================== @@ -15,7 +13,7 @@ Cookies contain a session ID -- not the data itself. Enabling sessions ================= -Sessions are implemented via a piece of :ref:`middleware <ref-middleware>`. +Sessions are implemented via a piece of :doc:`middleware </ref/middleware>`. To enable session functionality, do the following: @@ -56,8 +54,8 @@ For better performance, you may want to use a cache-based session backend. Django 1.0 did not include the ``cached_db`` session backend. To store session data using Django's cache system, you'll first need to make -sure you've configured your cache; see the :ref:`cache documentation -<topics-cache>` for details. +sure you've configured your cache; see the :doc:`cache documentation +</topics/cache>` for details. .. warning:: @@ -412,7 +410,7 @@ in the past -- but your application may have different requirements. Settings ======== -A few :ref:`Django settings <ref-settings>` give you control over session behavior: +A few :doc:`Django settings </ref/settings>` give you control over session behavior: SESSION_ENGINE -------------- diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt index 5510613355..6bd3058941 100644 --- a/docs/topics/http/shortcuts.txt +++ b/docs/topics/http/shortcuts.txt @@ -1,5 +1,3 @@ -.. _topics-http-shortcuts: - ========================= Django shortcut functions ========================= diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index 5a2980f9d2..1f499909ee 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -1,5 +1,3 @@ -.. _topics-http-urls: - ============== URL dispatcher ============== @@ -335,7 +333,7 @@ The view prefix You can specify a common prefix in your ``patterns()`` call, to cut down on code duplication. -Here's the example URLconf from the :ref:`Django overview <intro-overview>`:: +Here's the example URLconf from the :doc:`Django overview </intro/overview>`:: from django.conf.urls.defaults import * @@ -537,8 +535,8 @@ In this example, for a request to ``/blog/2005/``, Django will call the year='2005', foo='bar' -This technique is used in :ref:`generic views <ref-generic-views>` and in the -:ref:`syndication framework <ref-contrib-syndication>` to pass metadata and +This technique is used in :doc:`generic views </ref/generic-views>` and in the +:doc:`syndication framework </ref/contrib/syndication>` to pass metadata and options to views. .. admonition:: Dealing with conflicts @@ -827,17 +825,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. + +.. 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. -For example, it can be used for testing if a view would raise a ``Http404`` -error before redirecting to it:: + .. 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,9 +919,29 @@ error before redirecting to it:: return HttpResponseRedirect('/') return response + permalink() ----------- The :func:`django.db.models.permalink` decorator is useful for writing short methods that return a full URL path. For example, a model's ``get_absolute_url()`` method. See :func:`django.db.models.permalink` for more. + +get_script_prefix() +------------------- + +.. function:: get_script_prefix() + +.. versionadded:: 1.0 + +Normally, you should always use :func:`~django.core.urlresolvers.reverse` or +:func:`~django.db.models.permalink` to define URLs within your application. +However, if your application constructs part of the URL hierarchy itself, you +may occasionally need to generate URLs. In that case, you need to be able to +find the base URL of the Django project within its web server +(normally, :func:`~django.core.urlresolvers.reverse` takes care of this for +you). In that case, you can call ``get_script_prefix()``, which will return the +script prefix portion of the URL for your Django project. If your Django +project is at the root of its webserver, this is always ``"/"``, but it can be +changed, for instance by using ``django.root`` (see :ref:`How to use +Django with Apache and mod_python <howto-deployment-modpython>`). diff --git a/docs/topics/http/views.txt b/docs/topics/http/views.txt index 7d8743fe06..399e6b6ad1 100644 --- a/docs/topics/http/views.txt +++ b/docs/topics/http/views.txt @@ -1,5 +1,3 @@ -.. _topics-http-views: - ============= Writing Views ============= @@ -59,7 +57,7 @@ Mapping URLs to Views So, to recap, this view function returns an HTML page that includes the current date and time. To display this view at a particular URL, you'll need to create a -*URLconf*; see :ref:`topics-http-urls` for instructions. +*URLconf*; see :doc:`/topics/http/urls` for instructions. Returning errors ================ diff --git a/docs/topics/i18n/deployment.txt b/docs/topics/i18n/deployment.txt index 1a4f5fa4d5..f06227e0f6 100644 --- a/docs/topics/i18n/deployment.txt +++ b/docs/topics/i18n/deployment.txt @@ -1,5 +1,3 @@ -.. _topics-i18n-deployment: - ========================== Deployment of translations ========================== @@ -72,8 +70,8 @@ For example, your ``MIDDLEWARE_CLASSES`` might look like this:: 'django.middleware.common.CommonMiddleware', ) -(For more on middleware, see the :ref:`middleware documentation -<topics-http-middleware>`.) +(For more on middleware, see the :doc:`middleware documentation +</topics/http/middleware>`.) ``LocaleMiddleware`` tries to determine the user's language preference by following this algorithm: diff --git a/docs/topics/i18n/index.txt b/docs/topics/i18n/index.txt index e39a75067a..9c25192504 100644 --- a/docs/topics/i18n/index.txt +++ b/docs/topics/i18n/index.txt @@ -1,5 +1,3 @@ -.. _topics-i18n: - ===================================== Internationalization and localization ===================================== @@ -23,10 +21,10 @@ associated with each of these tasks (although it's perfectly normal if you find yourself performing more than one of these roles): * For application authors wishing to make sure their Django apps can be - used in different locales: :ref:`topics-i18n-internationalization`. - * For translators wanting to translate Django apps: :ref:`topics-i18n-localization`. + used in different locales: :doc:`/topics/i18n/internationalization`. + * For translators wanting to translate Django apps: :doc:`/topics/i18n/localization`. * For system administrators/final users setting up internationalized apps or - developers integrating third party apps: :ref:`topics-i18n-deployment`. + developers integrating third party apps: :doc:`/topics/i18n/deployment`. .. toctree:: :hidden: diff --git a/docs/topics/i18n/internationalization.txt b/docs/topics/i18n/internationalization.txt index 7ae8d18791..879c7739fb 100644 --- a/docs/topics/i18n/internationalization.txt +++ b/docs/topics/i18n/internationalization.txt @@ -1,5 +1,3 @@ -.. _topics-i18n-internationalization: - ==================== Internationalization ==================== @@ -242,7 +240,7 @@ If you don't like the verbose name ``ugettext_lazy``, you can just alias it as class MyThing(models.Model): name = models.CharField(help_text=_('This is the help text')) -Always use lazy translations in :ref:`Django models <topics-db-models>`. +Always use lazy translations in :doc:`Django models </topics/db/models>`. Field names and table names should be marked for translation (otherwise, they won't be translated in the admin interface). This means writing explicit ``verbose_name`` and ``verbose_name_plural`` options in the ``Meta`` class, @@ -332,7 +330,7 @@ Specifying translation strings: In template code .. highlightlang:: html+django -Translations in :ref:`Django templates <topics-templates>` uses two template +Translations in :doc:`Django templates </topics/templates>` uses two template tags and a slightly different syntax than in Python code. To give your template access to these tags, put ``{% load i18n %}`` toward the top of your template. @@ -569,7 +567,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/i18n/localization.txt b/docs/topics/i18n/localization.txt index ff8715571a..8ba1e1ecdc 100644 --- a/docs/topics/i18n/localization.txt +++ b/docs/topics/i18n/localization.txt @@ -1,5 +1,3 @@ -.. _topics-i18n-localization: - ============ Localization ============ @@ -12,7 +10,7 @@ files`_ and `locale aware date, time and numbers input/output in forms`_ .. seealso:: - The :ref:`howto-i18n` document included with the Django HOW-TO documents collection. + The :doc:`/howto/i18n` document included with the Django HOW-TO documents collection. .. _how-to-create-language-files: diff --git a/docs/topics/index.txt b/docs/topics/index.txt index 33f425a03e..4c6b7fc685 100644 --- a/docs/topics/index.txt +++ b/docs/topics/index.txt @@ -1,5 +1,3 @@ -.. _topics-index: - Using Django ============ diff --git a/docs/topics/install.txt b/docs/topics/install.txt index d53f49de46..2965c32ab6 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -1,5 +1,3 @@ -.. _topics-install: - ===================== How to install Django ===================== @@ -11,9 +9,9 @@ Install Python Being a Python Web framework, Django requires Python. -It works with any Python version from 2.4 to 2.6 (due to backwards +It works with any Python version from 2.4 to 2.7 (due to backwards incompatibilities in Python 3.0, Django does not currently work with -Python 3.0; see :ref:`the Django FAQ <faq-install>` for more +Python 3.0; see :doc:`the Django FAQ </faq/install>` for more information on supported Python versions and the 3.0 transition). Get Python at http://www.python.org. If you're running Linux or Mac OS X, you @@ -22,34 +20,45 @@ probably already have it installed. .. admonition:: Django on Jython If you use Jython_ (a Python implementation for the Java platform), you'll - need to follow a few additional steps. See :ref:`howto-jython` for details. + need to follow a few additional steps. See :doc:`/howto/jython` for details. .. _jython: http://jython.org/ Install Apache and mod_wsgi ============================= -If you just want to experiment with Django, skip ahead to the next section; -Django includes a lightweight web server you can use for testing, so you won't -need to set up Apache until you're ready to deploy Django in production. - -If you want to use Django on a production site, use Apache with `mod_wsgi`_. -mod_wsgi is similar to mod_perl -- it embeds Python within Apache and loads -Python code into memory when the server starts. Code stays in memory throughout -the life of an Apache process, which leads to significant performance gains over -other server arrangements. Make sure you have Apache installed, with the -mod_wsgi module activated. Django will work with any version of Apache that -supports mod_wsgi. - -See :ref:`How to use Django with mod_wsgi <howto-deployment-modwsgi>` for -information on how to configure mod_wsgi once you have it installed. - -If you can't use mod_wsgi for some reason, fear not: Django supports many other -deployment options. A great second choice is :ref:`mod_python -<howto-deployment-modpython>`, the predecessor to mod_wsgi. Additionally, Django -follows the WSGI_ spec, which allows it to run on a variety of server platforms. -See the `server-arrangements wiki page`_ for specific installation instructions -for each platform. +If you just want to experiment with Django, skip ahead to the next +section; Django includes a lightweight web server you can use for +testing, so you won't need to set up Apache until you're ready to +deploy Django in production. + +If you want to use Django on a production site, use Apache with +`mod_wsgi`_. mod_wsgi can operate in one of two modes: an embedded +mode and a daemon mode. In embedded mode, mod_wsgi is similar to +mod_perl -- it embeds Python within Apache and loads Python code into +memory when the server starts. Code stays in memory throughout the +life of an Apache process, which leads to significant performance +gains over other server arrangements. In daemon mode, mod_wsgi spawns +an independent daemon process that handles requests. The daemon +process can run as a different user than the webserver, possibly +leading to improved security, and the daemon process can be restarted +without restarting the entire Apache webserver, possibly making +refreshing your codebase more seamless. Consult the mod_wsgi +documentation to determine which mode is right for your setup. Make +sure you have Apache installed, with the mod_wsgi module activated. +Django will work with any version of Apache that supports mod_wsgi. + +See :doc:`How to use Django with mod_wsgi </howto/deployment/modwsgi>` +for information on how to configure mod_wsgi once you have it +installed. + +If you can't use mod_wsgi for some reason, fear not: Django supports +many other deployment options. Another option is :doc:`FastCGI +</howto/deployment/fastcgi>`, perfect for using Django with servers +other than Apache. Additionally, Django follows the WSGI_ spec, which +allows it to run on a variety of server platforms. See the +`server-arrangements wiki page`_ for specific installation +instructions for each platform. .. _Apache: http://httpd.apache.org/ .. _mod_wsgi: http://code.google.com/p/modwsgi/ @@ -90,8 +99,8 @@ database bindings are installed. If you're on Windows, check out the unofficial `compiled Windows version`_. * If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher. You - will also want to read the database-specific notes for the :ref:`MySQL - backend <ref-databases>`. + will also want to read the database-specific notes for the :doc:`MySQL + backend </ref/databases>`. * If you're using SQLite and Python 2.4, you'll need pysqlite_. Use version 2.0.3 or higher. Python 2.5 ships with an SQLite wrapper in the standard @@ -115,7 +124,7 @@ can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and ``ALTER TABLE`` privileges during ``syncdb`` but won't issue ``ALTER TABLE`` statements on a table once ``syncdb`` has created it. -If you're using Django's :ref:`testing framework<topics-testing>` to test database queries, +If you're using Django's :doc:`testing framework</topics/testing>` to test database queries, Django will need permission to create a test database. .. _PostgreSQL: http://www.postgresql.org/ @@ -177,7 +186,7 @@ It's easy, no matter which way you choose. Installing a distribution-specific package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Check the :ref:`distribution specific notes <misc-distributions>` to see if your +Check the :doc:`distribution specific notes </misc/distributions>` to see if your platform/distribution provides official Django packages/installers. Distribution-provided packages will typically allow for automatic installation of dependencies and easy upgrade paths. @@ -257,15 +266,15 @@ latest bug fixes and improvements, follow these instructions: links. (Environment variables can be defined on Windows systems `from the Control Panel`_.) - .. admonition:: What about Apache and mod_python? + .. admonition:: What about Apache and mod_wsgi? - If you take the approach of setting ``PYTHONPATH``, you'll need to - remember to do the same thing in your Apache configuration once you - deploy your production site. Do this by setting ``PythonPath`` in your - Apache configuration file. + If you take the approach of setting ``PYTHONPATH``, you'll need + to remember to do the same thing in your WSGI application once + you deploy your production site. Do this by appending to + ``sys.path`` in your WSGI application. More information about deployment is available, of course, in our - :ref:`How to use Django with mod_python <howto-deployment-modpython>` + :doc:`How to use Django with mod_wsgi </howto/deployment/modwsgi>` documentation. 4. On Unix-like systems, create a symbolic link to the file diff --git a/docs/topics/pagination.txt b/docs/topics/pagination.txt index 70f087bd84..ee8a43379a 100644 --- a/docs/topics/pagination.txt +++ b/docs/topics/pagination.txt @@ -1,5 +1,3 @@ -.. _topics-pagination: - ========== Pagination ========== diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt index 1cf8e86462..c8acc8539e 100644 --- a/docs/topics/serialization.txt +++ b/docs/topics/serialization.txt @@ -1,5 +1,3 @@ -.. _topics-serialization: - ========================== Serializing Django objects ========================== @@ -141,10 +139,6 @@ to install third-party Python modules: ``json`` Serializes to and from JSON_ (using a version of simplejson_ bundled with Django). - ``python`` Translates to and from "simple" Python objects (lists, dicts, - strings, etc.). Not really all that useful on its own, but - used as a base for other serializers. - ``yaml`` Serializes to YAML (YAML Ain't a Markup Language). This serializer is only available if PyYAML_ is installed. ========== ============================================================== @@ -169,7 +163,7 @@ For example:: json_serializer.serialize(queryset, ensure_ascii=False, stream=response) The Django source code includes the simplejson_ module. However, if you're -using Python 2.6 (which includes a builtin version of the module), Django will +using Python 2.6 or later (which includes a builtin version of the module), Django will use the builtin ``json`` module automatically. If you have a system installed version that includes the C-based speedup extension, or your system version is more recent than the version shipped with Django (currently, 2.0.7), the @@ -338,7 +332,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 diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt index 9e6a689588..6d96190a90 100644 --- a/docs/topics/settings.txt +++ b/docs/topics/settings.txt @@ -1,5 +1,3 @@ -.. _topics-settings: - =============== Django settings =============== @@ -46,7 +44,7 @@ Python `import search path`_. The django-admin.py utility --------------------------- -When using :ref:`django-admin.py <ref-django-admin>`, you can either set the +When using :doc:`django-admin.py </ref/django-admin>`, you can either set the environment variable once, or explicitly pass in the settings module each time you run the utility. @@ -66,20 +64,19 @@ Use the ``--settings`` command-line argument to specify the settings manually:: .. _django-admin.py: ../django-admin/ -On the server (mod_python) +On the server (mod_wsgi) -------------------------- -In your live server environment, you'll need to tell Apache/mod_python which -settings file to use. Do that with ``SetEnv``:: +In your live server environment, you'll need to tell your WSGI +application what settings file to use. Do that with ``os.environ``:: + + import os - <Location "/mysite/"> - SetHandler python-program - PythonHandler django.core.handlers.modpython - SetEnv DJANGO_SETTINGS_MODULE mysite.settings - </Location> + os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings' -Read the :ref:`Django mod_python documentation <howto-deployment-modpython>` for -more information. +Read the :doc:`Django mod_wsgi documentation +</howto/deployment/modwsgi>` for more information and other common +elements to a Django WSGI application. Default settings ================ @@ -151,7 +148,7 @@ read it. This is especially important in a shared-hosting environment. Available settings ================== -For a full list of available settings, see the :ref:`settings reference <ref-settings>`. +For a full list of available settings, see the :doc:`settings reference </ref/settings>`. Creating your own settings ========================== diff --git a/docs/topics/signals.txt b/docs/topics/signals.txt index eb1a5fd825..78790db071 100644 --- a/docs/topics/signals.txt +++ b/docs/topics/signals.txt @@ -1,5 +1,3 @@ -.. _topics-signals: - ======= Signals ======= @@ -13,7 +11,7 @@ signals allow certain *senders* to notify a set of *receivers* that some action has taken place. They're especially useful when many pieces of code may be interested in the same events. -Django provides a :ref:`set of built-in signals <ref-signals>` that let user +Django provides a :doc:`set of built-in signals </ref/signals>` that let user code get notified by Django itself of certain actions. These include some useful notifications: @@ -38,7 +36,7 @@ notifications: Sent when Django starts or finishes an HTTP request. -See the :ref:`built-in signal documentation <ref-signals>` for a complete list, +See the :doc:`built-in signal documentation </ref/signals>` for a complete list, and a complete explanation of each signal. You can also `define and send your own custom signals`_; see below. @@ -82,7 +80,8 @@ must be able to handle those new arguments. Connecting receiver functions ----------------------------- -Next, we'll need to connect our receiver to the signal: +There are two ways you can connect a receiever to a signal. You can take the +manual connect route: .. code-block:: python @@ -90,6 +89,17 @@ Next, we'll need to connect our receiver to the signal: request_finished.connect(my_callback) +Alternatively, you can use a decorator used when you define your receiver: + +.. code-block:: python + + from django.core.signals import request_finished + from django.dispatch import receiver + + @receiver(request_finished) + def my_callback(sender, **kwargs): + print "Request finished!" + Now, our ``my_callback`` function will be called each time a request finishes. .. admonition:: Where should this code live? @@ -117,18 +127,18 @@ signals sent by some model: .. code-block:: python from django.db.models.signals import pre_save + from django.dispatch import receiver from myapp.models import MyModel + @receiver(pre_save, sender=MyModel) def my_handler(sender, **kwargs): ... - pre_save.connect(my_handler, sender=MyModel) - The ``my_handler`` function will only be called when an instance of ``MyModel`` is saved. Different signals use different objects as their senders; you'll need to consult -the :ref:`built-in signal documentation <ref-signals>` for details of each +the :doc:`built-in signal documentation </ref/signals>` for details of each particular signal. Defining and sending signals diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index 9fa6c44dc9..492d23d716 100644 --- a/docs/topics/templates.txt +++ b/docs/topics/templates.txt @@ -1,5 +1,3 @@ -.. _topics-templates: - ============================ The Django template language ============================ @@ -8,7 +6,7 @@ The Django template language This document explains the language syntax of the Django template system. If you're looking for a more technical perspective on how it works and how to - extend it, see :ref:`ref-templates-api`. + extend it, see :doc:`/ref/templates/api`. Django's template language is designed to strike a balance between power and ease. It's designed to feel comfortable to those used to working with HTML. If @@ -28,8 +26,8 @@ or CheetahTemplate_, you should feel right at home with Django's templates. tag for looping, etc. -- but these are not simply executed as the corresponding Python code, and the template system will not execute arbitrary Python expressions. Only the tags, filters and syntax listed below - are supported by default (although you can add :ref:`your own extensions - <howto-custom-template-tags>` to the template language as needed). + are supported by default (although you can add :doc:`your own extensions + </howto/custom-template-tags>` to the template language as needed). .. _`The Django template language: For Python programmers`: ../templates_python/ .. _Smarty: http://smarty.php.net/ @@ -140,7 +138,7 @@ template filters: If ``value`` isn't provided or is empty, the above will display "``nothing``". - + :tfilter:`length` Returns the length of the value. This works for both strings and lists; for example:: @@ -148,7 +146,7 @@ template filters: {{ value|length }} If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``. - + :tfilter:`striptags` Strips all [X]HTML tags. For example:: @@ -161,7 +159,7 @@ Again, these are just a few examples; see the :ref:`built-in filter reference <ref-templates-builtins-filters>` for the complete list. You can also create your own custom template filters; see -:ref:`howto-custom-template-tags`. +:doc:`/howto/custom-template-tags`. Tags ==== @@ -217,7 +215,7 @@ Again, the above is only a selection of the whole list; see the :ref:`built-in tag reference <ref-templates-builtins-tags>` for the complete list. You can also create your own custom template tags; see -:ref:`howto-custom-template-tags`. +:doc:`/howto/custom-template-tags`. Comments ======== @@ -571,6 +569,45 @@ This doesn't affect what happens to data coming from the variable itself. The variable's contents are still automatically escaped, if necessary, because they're beyond the control of the template author. +.. _template-accessing-methods: + +Accessing method calls +====================== + +Most method calls attached to objects are also available from within templates. +This means that templates have access to much more than just class attributes +(like field names) and variables passed in from views. For example, the Django +ORM provides the :ref:`"entry_set"<topics-db-queries-related>` syntax for +finding a collection of objects related on a foreign key. Therefore, given +a model called "comment" with a foreign key relationship to a model called +"task" you can loop through all comments attached to a given task like this:: + + {% for comment in task.comment_set.all %} + {{ comment }} + {% endfor %} + +Similarly, :doc:`QuerySets<ref/models/querysets>` provide a ``count()`` method +to count the number of objects they contain. Therefore, you can obtain a count +of all comments related to the current task with:: + + {{ task.comment_set.all.count }} + +And of course you can easily access methods you've explicitly defined on your +own models:: + + # In model + class Task(models.Model): + def foo(self): + return "bar" + + # In template + {{ task.foo }} + +Because Django intentionally limits the amount of logic processing available +in the template language, it is not possible to pass arguments to method calls +accessed from within templates. Data should be calculated in views, then passed +to templates for display. + .. _template-built-in-reference: Using the built-in reference @@ -634,8 +671,8 @@ The ``{% load %}`` tag can take multiple library names, separated by spaces. Example:: {% load comments i18n %} - -See :ref:`howto-custom-template-tags` for information on writing your own custom + +See :doc:`/howto/custom-template-tags` for information on writing your own custom template libraries. Custom libraries and template inheritance diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt index bd727ee136..5c1933c946 100644 --- a/docs/topics/testing.txt +++ b/docs/topics/testing.txt @@ -1,5 +1,3 @@ -.. _topics-testing: - =========================== Testing Django applications =========================== @@ -311,6 +309,24 @@ can press ``Ctrl-C`` a second time and the test run will halt immediately, but not gracefully. No details of the tests run before the interruption will be reported, and any test databases created by the run will not be destroyed. +Running tests outside the test runner +------------------------------------- + +If you want to run tests outside of ``./manage.py test`` -- for example, +from a shell prompt -- you will need to set up the test +environment first. Django provides a convenience method to do this:: + + >>> from django.test.utils import setup_test_environment + >>> setup_test_environment() + +This convenience method sets up the test database, and puts other +Django features into modes that allow for repeatable testing. + +The call to :meth:`~django.test.utils.setup_test_environment` is made +automatically as part of the setup of `./manage.py test`. You only +need to manually invoke this method if you're not using running your +tests via Django's test runner. + The test database ----------------- @@ -342,7 +358,7 @@ For fine-grained control over the character encoding of your test database, use the :setting:`TEST_CHARSET` option. If you're using MySQL, you can also use the :setting:`TEST_COLLATION` option to control the particular collation used by the test database. See the -:ref:`settings documentation <ref-settings>` for details of these +:doc:`settings documentation </ref/settings>` for details of these advanced settings. .. _topics-testing-masterslave: @@ -401,7 +417,7 @@ Other test conditions --------------------- Regardless of the value of the :setting:`DEBUG` setting in your configuration -file, all Django tests run with :setting:`DEBUG=False`. This is to ensure that +file, all Django tests run with :setting:`DEBUG`\=False. This is to ensure that the observed output of your code matches what will be seen in a production setting. @@ -556,6 +572,19 @@ Note a few important things about how the test client works: This black magic (essentially a patching of Django's template system in memory) only happens during test running. + * By default, the test client will disable any CSRF checks + performed by your site. + + If, for some reason, you *want* the test client to perform CSRF + checks, you can create an instance of the test client that + enforces CSRF checks. To do this, pass in the + ``enforce_csrf_checks`` argument when you construct your + client:: + + >>> from django.test import Client + >>> csrf_client = Client(enforce_csrf_checks=True) + + .. _urllib: http://docs.python.org/library/urllib.html .. _urllib2: http://docs.python.org/library/urllib2.html @@ -751,7 +780,7 @@ arguments at time of construction: .. versionadded:: 1.0 - If your site uses Django's :ref:`authentication system<topics-auth>` + If your site uses Django's :doc:`authentication system</topics/auth>` and you deal with logging in users, you can use the test client's ``login()`` method to simulate the effect of a user logging into the site. @@ -797,7 +826,7 @@ arguments at time of construction: .. versionadded:: 1.0 - If your site uses Django's :ref:`authentication system<topics-auth>`, + If your site uses Django's :doc:`authentication system</topics/auth>`, the ``logout()`` method can be used to simulate the effect of a user logging out of your site. @@ -904,7 +933,16 @@ can access these properties as part of a test condition. .. attribute:: Client.session A dictionary-like object containing session information. See the - :ref:`session documentation<topics-http-sessions>` for full details. + :doc:`session documentation</topics/http/sessions>` for full details. + + To modify the session and then save it, it must be stored in a variable + first (because a new ``SessionStore`` is created every time this property + is accessed):: + + def test_something(self): + session = self.client.session + session['somekey'] = 'test' + session.save() .. _Cookie module documentation: http://docs.python.org/library/cookie.html @@ -1052,23 +1090,25 @@ A fixture is a collection of data that Django knows how to import into a database. For example, if your site has user accounts, you might set up a fixture of fake user accounts in order to populate your database during tests. -The most straightforward way of creating a fixture is to use the ``manage.py -dumpdata`` command. This assumes you already have some data in your database. -See the :djadmin:`dumpdata documentation<dumpdata>` for more details. +The most straightforward way of creating a fixture is to use the +:djadmin:`manage.py dumpdata <dumpdata>` command. This assumes you +already have some data in your database. See the :djadmin:`dumpdata +documentation<dumpdata>` for more details. .. note:: - If you've ever run ``manage.py syncdb``, you've already used a fixture - without even knowing it! When you call ``syncdb`` in the database for - the first time, Django installs a fixture called ``initial_data``. - This gives you a way of populating a new database with any initial data, - such as a default set of categories. + If you've ever run :djadmin:`manage.py syncdb<syncdb>`, you've + already used a fixture without even knowing it! When you call + :djadmin:`syncdb` in the database for the first time, Django + installs a fixture called ``initial_data``. This gives you a way + of populating a new database with any initial data, such as a + default set of categories. - Fixtures with other names can always be installed manually using the - ``manage.py loaddata`` command. + Fixtures with other names can always be installed manually using + the :djadmin:`manage.py loaddata<loaddata>` command. Once you've created a fixture and placed it in a ``fixtures`` directory in one of your :setting:`INSTALLED_APPS`, you can use it in your unit tests by -specifying a ``fixtures`` class attribute on your ``django.test.TestCase`` +specifying a ``fixtures`` class attribute on your :class:`django.test.TestCase` subclass:: from django.test import TestCase @@ -1248,6 +1288,21 @@ cause of an failure in your test suite. ``target_status_code`` will be the url and status code for the final point of the redirect chain. +.. method:: TestCase.assertQuerysetEqual(qs, values, transform=repr) + + .. versionadded:: 1.3 + + Asserts that a queryset ``qs`` returns a particular list of values ``values``. + + The comparison of the contents of ``qs`` and ``values`` is performed using + the function ``transform``; by default, this means that the ``repr()`` of + each value is compared. Any other callable can be used if ``repr()`` doesn't + provide a unique or helpful comparison. + + The comparison is also ordering dependent. If ``qs`` doesn't provide an + implicit ordering, you will need to apply a ``order_by()`` clause to your + queryset to ensure that the test will pass reliably. + .. _topics-testing-email: E-mail services @@ -1255,8 +1310,8 @@ E-mail services .. versionadded:: 1.0 -If any of your Django views send e-mail using :ref:`Django's e-mail -functionality <topics-email>`, you probably don't want to send e-mail each time +If any of your Django views send e-mail using :doc:`Django's e-mail +functionality </topics/email>`, you probably don't want to send e-mail each time you run a test using that view. For this reason, Django's test runner automatically redirects all Django-sent e-mail to a dummy outbox. This lets you test every aspect of sending e-mail -- from the number of messages sent to the |
