diff options
Diffstat (limited to 'docs/ref')
45 files changed, 455 insertions, 442 deletions
diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt index dd8a81d800..2f48c6b306 100644 --- a/docs/ref/class-based-views/base.txt +++ b/docs/ref/class-based-views/base.txt @@ -14,7 +14,7 @@ ancestor classes are documented under the section title of **Ancestors (MRO)**. MRO is an acronym for Method Resolution Order. View ----- +==== .. class:: django.views.generic.base.View @@ -103,7 +103,7 @@ View list of the allowed HTTP method names for the view. TemplateView ------------- +============ .. class:: django.views.generic.base.TemplateView @@ -155,7 +155,7 @@ TemplateView the keyword arguments captured from the URL pattern that served the view. RedirectView ------------- +============ .. class:: django.views.generic.base.RedirectView diff --git a/docs/ref/class-based-views/flattened-index.txt b/docs/ref/class-based-views/flattened-index.txt index 9107d43d8b..d549cd4245 100644 --- a/docs/ref/class-based-views/flattened-index.txt +++ b/docs/ref/class-based-views/flattened-index.txt @@ -9,10 +9,10 @@ documentation organized by the class which defines the behavior, see :doc:`Class-based views</ref/class-based-views/index>` Simple generic views --------------------- +==================== View -~~~~ +---- .. class:: View() **Attributes** (with optional accessor): @@ -27,7 +27,7 @@ View * :meth:`~django.views.generic.base.View.http_method_not_allowed` TemplateView -~~~~~~~~~~~~ +------------ .. class:: TemplateView() **Attributes** (with optional accessor): @@ -49,7 +49,7 @@ TemplateView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` RedirectView -~~~~~~~~~~~~ +------------ .. class:: RedirectView() **Attributes** (with optional accessor): @@ -73,10 +73,10 @@ RedirectView * ``put()`` Detail Views ------------- +============ DetailView -~~~~~~~~~~ +---------- .. class:: DetailView() **Attributes** (with optional accessor): @@ -107,10 +107,10 @@ DetailView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` List Views ----------- +========== ListView -~~~~~~~~ +-------- .. class:: ListView() **Attributes** (with optional accessor): @@ -143,10 +143,10 @@ ListView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` Editing views -------------- +============= FormView -~~~~~~~~ +-------- .. class:: FormView() **Attributes** (with optional accessor): @@ -176,7 +176,7 @@ FormView * :meth:`~django.views.generic.edit.ProcessFormView.put` CreateView -~~~~~~~~~~ +---------- .. class:: CreateView() **Attributes** (with optional accessor): @@ -218,7 +218,7 @@ CreateView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` UpdateView -~~~~~~~~~~ +---------- .. class:: UpdateView() **Attributes** (with optional accessor): @@ -260,7 +260,7 @@ UpdateView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` DeleteView -~~~~~~~~~~ +---------- .. class:: DeleteView() **Attributes** (with optional accessor): @@ -294,10 +294,10 @@ DeleteView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` Date-based views ----------------- +================ ArchiveIndexView -~~~~~~~~~~~~~~~~ +---------------- .. class:: ArchiveIndexView() **Attributes** (with optional accessor): @@ -335,7 +335,7 @@ ArchiveIndexView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` YearArchiveView -~~~~~~~~~~~~~~~ +--------------- .. class:: YearArchiveView() **Attributes** (with optional accessor): @@ -376,7 +376,7 @@ YearArchiveView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` MonthArchiveView -~~~~~~~~~~~~~~~~ +---------------- .. class:: MonthArchiveView() **Attributes** (with optional accessor): @@ -420,7 +420,7 @@ MonthArchiveView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` WeekArchiveView -~~~~~~~~~~~~~~~ +--------------- .. class:: WeekArchiveView() **Attributes** (with optional accessor): @@ -462,7 +462,7 @@ WeekArchiveView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` DayArchiveView -~~~~~~~~~~~~~~ +-------------- .. class:: DayArchiveView() **Attributes** (with optional accessor): @@ -510,7 +510,7 @@ DayArchiveView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` TodayArchiveView -~~~~~~~~~~~~~~~~ +---------------- .. class:: TodayArchiveView() **Attributes** (with optional accessor): @@ -558,7 +558,7 @@ TodayArchiveView * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` DateDetailView -~~~~~~~~~~~~~~ +-------------- .. class:: DateDetailView() **Attributes** (with optional accessor): diff --git a/docs/ref/class-based-views/generic-date-based.txt b/docs/ref/class-based-views/generic-date-based.txt index b03e34858e..16a3ff147e 100644 --- a/docs/ref/class-based-views/generic-date-based.txt +++ b/docs/ref/class-based-views/generic-date-based.txt @@ -23,7 +23,7 @@ views for displaying drilldown pages for date-based data. return reverse('article-detail', kwargs={'pk': self.pk}) ArchiveIndexView ----------------- +================ .. class:: ArchiveIndexView @@ -87,7 +87,7 @@ ArchiveIndexView This will output all articles. YearArchiveView ---------------- +=============== .. class:: YearArchiveView @@ -192,7 +192,7 @@ YearArchiveView </div> MonthArchiveView ----------------- +================ .. class:: MonthArchiveView @@ -289,7 +289,7 @@ MonthArchiveView </p> WeekArchiveView ---------------- +=============== .. class:: WeekArchiveView @@ -392,7 +392,7 @@ WeekArchiveView filter ``'%U'`` outputs the number of seconds since the Unix epoch. DayArchiveView --------------- +============== .. class:: DayArchiveView @@ -494,7 +494,7 @@ DayArchiveView </p> TodayArchiveView ----------------- +================ .. class:: TodayArchiveView @@ -551,7 +551,7 @@ TodayArchiveView name of the new template. DateDetailView --------------- +============== .. class:: DateDetailView diff --git a/docs/ref/class-based-views/generic-display.txt b/docs/ref/class-based-views/generic-display.txt index 5dc0391319..8f45ce654b 100644 --- a/docs/ref/class-based-views/generic-display.txt +++ b/docs/ref/class-based-views/generic-display.txt @@ -6,7 +6,7 @@ The two following generic class-based views are designed to display data. On many projects they are typically the most commonly used views. DetailView ----------- +========== .. class:: django.views.generic.detail.DetailView @@ -73,7 +73,7 @@ DetailView <p>Date: {{ now|date }}</p> ListView --------- +======== .. class:: django.views.generic.list.ListView diff --git a/docs/ref/class-based-views/generic-editing.txt b/docs/ref/class-based-views/generic-editing.txt index d726c0a3cb..c59870c4f0 100644 --- a/docs/ref/class-based-views/generic-editing.txt +++ b/docs/ref/class-based-views/generic-editing.txt @@ -25,7 +25,7 @@ editing content: return reverse('author-detail', kwargs={'pk': self.pk}) FormView --------- +======== .. class:: django.views.generic.edit.FormView @@ -81,7 +81,7 @@ FormView CreateView ----------- +========== .. class:: django.views.generic.edit.CreateView @@ -136,7 +136,7 @@ CreateView </form> UpdateView ----------- +========== .. class:: django.views.generic.edit.UpdateView @@ -193,7 +193,7 @@ UpdateView </form> DeleteView ----------- +========== .. class:: django.views.generic.edit.DeleteView diff --git a/docs/ref/class-based-views/index.txt b/docs/ref/class-based-views/index.txt index b5ba62dbc3..5670849562 100644 --- a/docs/ref/class-based-views/index.txt +++ b/docs/ref/class-based-views/index.txt @@ -16,7 +16,7 @@ Class-based views API reference. For introductory material, see the flattened-index Specification -------------- +============= Each request served by a class-based view has an independent state; therefore, it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is @@ -44,7 +44,7 @@ previous example, this means that every request on ``MyView`` is able to use the class (return ``True`` on a ``hasattr`` check). Base vs Generic views ---------------------- +===================== Base class-based views can be thought of as *parent* views, which can be used by themselves or inherited from. They may not provide all the diff --git a/docs/ref/class-based-views/mixins-date-based.txt b/docs/ref/class-based-views/mixins-date-based.txt index 020fc918b8..921d3dee0d 100644 --- a/docs/ref/class-based-views/mixins-date-based.txt +++ b/docs/ref/class-based-views/mixins-date-based.txt @@ -11,7 +11,7 @@ Date-based mixins characters from the :ttag:`now` template tag as they are not compatible. YearMixin ---------- +========= .. class:: YearMixin @@ -63,7 +63,7 @@ YearMixin :attr:`~DateMixin.allow_future`. MonthMixin ----------- +========== .. class:: MonthMixin @@ -115,7 +115,7 @@ MonthMixin :attr:`~DateMixin.allow_future`. DayMixin --------- +======== .. class:: DayMixin @@ -167,7 +167,7 @@ DayMixin :attr:`~DateMixin.allow_future`. WeekMixin ---------- +========= .. class:: WeekMixin @@ -220,7 +220,7 @@ WeekMixin :attr:`~DateMixin.allow_future`. DateMixin ---------- +========= .. class:: DateMixin @@ -266,7 +266,7 @@ DateMixin :attr:`~DateMixin.allow_future` by default. BaseDateListView ----------------- +================ .. class:: BaseDateListView diff --git a/docs/ref/class-based-views/mixins-editing.txt b/docs/ref/class-based-views/mixins-editing.txt index 29e1f05a8e..2676cbf0bc 100644 --- a/docs/ref/class-based-views/mixins-editing.txt +++ b/docs/ref/class-based-views/mixins-editing.txt @@ -15,7 +15,7 @@ The following mixins are used to construct Django's editing views: the documentation on :doc:`/ref/class-based-views/generic-editing`. FormMixin ---------- +========= .. class:: django.views.generic.edit.FormMixin @@ -95,7 +95,7 @@ FormMixin name 'form'. ModelFormMixin --------------- +============== .. class:: django.views.generic.edit.ModelFormMixin @@ -181,7 +181,7 @@ ModelFormMixin ProcessFormView ---------------- +=============== .. class:: django.views.generic.edit.ProcessFormView @@ -221,7 +221,7 @@ ProcessFormView DeletionMixin -------------- +============= .. class:: django.views.generic.edit.DeletionMixin diff --git a/docs/ref/class-based-views/mixins-multiple-object.txt b/docs/ref/class-based-views/mixins-multiple-object.txt index 6c4cdadedf..8b30d91f23 100644 --- a/docs/ref/class-based-views/mixins-multiple-object.txt +++ b/docs/ref/class-based-views/mixins-multiple-object.txt @@ -3,7 +3,7 @@ Multiple object mixins ====================== MultipleObjectMixin -------------------- +=================== .. class:: django.views.generic.list.MultipleObjectMixin @@ -193,7 +193,7 @@ MultipleObjectMixin MultipleObjectTemplateResponseMixin ------------------------------------ +=================================== .. class:: django.views.generic.list.MultipleObjectTemplateResponseMixin diff --git a/docs/ref/class-based-views/mixins-simple.txt b/docs/ref/class-based-views/mixins-simple.txt index 9550c22ed4..e6fd4ac3f4 100644 --- a/docs/ref/class-based-views/mixins-simple.txt +++ b/docs/ref/class-based-views/mixins-simple.txt @@ -3,7 +3,7 @@ Simple mixins ============= ContextMixin ------------- +============ .. class:: django.views.generic.base.ContextMixin @@ -32,7 +32,7 @@ ContextMixin <alters-data-description>`. TemplateResponseMixin ---------------------- +===================== .. class:: django.views.generic.base.TemplateResponseMixin diff --git a/docs/ref/class-based-views/mixins-single-object.txt b/docs/ref/class-based-views/mixins-single-object.txt index 02c1437526..d04f5dc5a1 100644 --- a/docs/ref/class-based-views/mixins-single-object.txt +++ b/docs/ref/class-based-views/mixins-single-object.txt @@ -3,7 +3,7 @@ Single object mixins ==================== SingleObjectMixin ------------------ +================= .. class:: django.views.generic.detail.SingleObjectMixin @@ -132,7 +132,7 @@ SingleObjectMixin SingleObjectTemplateResponseMixin ---------------------------------- +================================= .. class:: django.views.generic.detail.SingleObjectTemplateResponseMixin diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt index ed51b5ea8f..5f8f5a21d4 100644 --- a/docs/ref/clickjacking.txt +++ b/docs/ref/clickjacking.txt @@ -52,7 +52,7 @@ How to use it ============= Setting X-Frame-Options for all responses -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------------- To set the same ``X-Frame-Options`` value for all responses in your site, put ``'django.middleware.clickjacking.XFrameOptionsMiddleware'`` to @@ -86,7 +86,7 @@ that tells the middleware not to set the header:: Setting X-Frame-Options per view -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------- To set the ``X-Frame-Options`` header on a per view basis, Django provides these decorators:: @@ -114,7 +114,7 @@ modern browser. Older browsers will quietly ignore the header and need `other clickjacking prevention techniques`_. Browsers that support X-Frame-Options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------- * Internet Explorer 8+ * Firefox 3.6.9+ @@ -123,7 +123,7 @@ Browsers that support X-Frame-Options * Chrome 4.1+ See also -~~~~~~~~ +-------- A `complete list`_ of browsers supporting ``X-Frame-Options``. diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index e4c31731d5..66906d5ddc 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -1,3 +1,4 @@ +======================= ``django.contrib.auth`` ======================= diff --git a/docs/ref/contrib/gis/forms-api.txt b/docs/ref/contrib/gis/forms-api.txt index b9c0c1dbe4..c2593acba6 100644 --- a/docs/ref/contrib/gis/forms-api.txt +++ b/docs/ref/contrib/gis/forms-api.txt @@ -18,7 +18,7 @@ In addition to the regular :ref:`form field arguments <core-field-arguments>`, GeoDjango form fields take the following optional arguments. ``srid`` -~~~~~~~~ +-------- .. attribute:: Field.srid @@ -28,7 +28,7 @@ GeoDjango form fields take the following optional arguments. input values into that SRID. ``geom_type`` -~~~~~~~~~~~~~ +------------- .. attribute:: Field.geom_type @@ -40,42 +40,42 @@ Form field classes ================== ``GeometryField`` -~~~~~~~~~~~~~~~~~ +----------------- .. class:: GeometryField ``PointField`` -~~~~~~~~~~~~~~ +-------------- .. class:: PointField ``LineStringField`` -~~~~~~~~~~~~~~~~~~~ +------------------- .. class:: LineStringField ``PolygonField`` -~~~~~~~~~~~~~~~~ +---------------- .. class:: PolygonField ``MultiPointField`` -~~~~~~~~~~~~~~~~~~~ +------------------- .. class:: MultiPointField ``MultiLineStringField`` -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ .. class:: MultiLineStringField ``MultiPolygonField`` -~~~~~~~~~~~~~~~~~~~~~ +--------------------- .. class:: MultiPolygonField ``GeometryCollectionField`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- .. class:: GeometryCollectionField @@ -91,7 +91,7 @@ Note that none of the currently available widgets supports 3D geometries, hence geometry fields will fallback using a simple ``Textarea`` widget for such data. Widget attributes -~~~~~~~~~~~~~~~~~ +----------------- GeoDjango widgets are template-based, so their attributes are mostly different from other Django widget attributes. @@ -134,7 +134,7 @@ widget. For example:: forms.OSMWidget(attrs={'map_width': 800, 'map_height': 500})) Widget classes -~~~~~~~~~~~~~~ +-------------- ``BaseGeometryWidget`` diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt index 4ac7a4bc72..282fe55a38 100644 --- a/docs/ref/contrib/gis/functions.txt +++ b/docs/ref/contrib/gis/functions.txt @@ -36,7 +36,7 @@ Measurement Relationships Operations Editors ================== ======================= ====================== =================== ================== ===================== Area ----- +==== .. class:: Area(expression, **extra) @@ -48,7 +48,7 @@ float value is returned, as it's not possible to automatically determine the unit of the field. AsGeoJSON ---------- +========= .. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra) @@ -80,7 +80,7 @@ Keyword Argument Description ===================== ===================================================== AsGML ------ +===== .. class:: AsGML(expression, version=2, precision=8, **extra) @@ -111,7 +111,7 @@ Keyword Argument Description __ https://en.wikipedia.org/wiki/Geography_Markup_Language AsKML ------ +===== .. class:: AsKML(expression, precision=8, **extra) @@ -138,7 +138,7 @@ Keyword Argument Description __ https://developers.google.com/kml/documentation/ AsSVG ------ +===== .. class:: AsSVG(expression, relative=False, precision=8, **extra) @@ -162,7 +162,7 @@ Keyword Argument Description __ http://www.w3.org/Graphics/SVG/ BoundingCircle --------------- +============== .. class:: BoundingCircle(expression, num_seg=48, **extra) @@ -172,7 +172,7 @@ Accepts a single geographic field or expression and returns the smallest circle polygon that can fully contain the geometry. Centroid --------- +======== .. class:: Centroid(expression, **extra) @@ -182,7 +182,7 @@ Accepts a single geographic field or expression and returns the ``centroid`` value of the geometry. Difference ----------- +========== .. class:: Difference(expr1, expr2, **extra) @@ -197,7 +197,7 @@ geometry B. MySQL support was added. Distance --------- +======== .. class:: Distance(expr1, expr2, spheroid=None, **extra) @@ -241,7 +241,7 @@ queryset is calculated:: :ref:`supported_units`. Envelope --------- +======== .. class:: Envelope(expression, **extra) @@ -251,7 +251,7 @@ Accepts a single geographic field or expression and returns the geometry representing the bounding box of the geometry. ForceRHR --------- +======== .. class:: ForceRHR(expression, **extra) @@ -262,7 +262,7 @@ of the polygon/multipolygon in which all of the vertices follow the right-hand rule. GeoHash -------- +======= .. class:: GeoHash(expression, **extra) @@ -278,7 +278,7 @@ representation of the geometry. __ https://en.wikipedia.org/wiki/Geohash Intersection ------------- +============ .. class:: Intersection(expr1, expr2, **extra) @@ -292,7 +292,7 @@ intersection between them. MySQL support was added. Length ------- +====== .. class:: Length(expression, spheroid=True, **extra) @@ -309,7 +309,7 @@ accurate, less resource-intensive) or on a spheroid (more accurate, more resource-intensive) with the ``spheroid`` keyword argument. MemSize -------- +======= .. class:: MemSize(expression, **extra) @@ -319,7 +319,7 @@ Accepts a single geographic field or expression and returns the memory size (number of bytes) that the geometry field takes. NumGeometries -------------- +============= .. class:: NumGeometries(expression, **extra) @@ -330,7 +330,7 @@ geometries if the geometry field is a collection (e.g., a ``GEOMETRYCOLLECTION`` or ``MULTI*`` field); otherwise returns ``None``. NumPoints ---------- +========= .. class:: NumPoints(expression, **extra) @@ -340,7 +340,7 @@ Accepts a single geographic field or expression and returns the number of points in the first linestring in the geometry field; otherwise returns ``None``. Perimeter ---------- +========= .. class:: Perimeter(expression, **extra) @@ -352,7 +352,7 @@ MySQL, a raw float value is returned, as it's not possible to automatically determine the unit of the field. PointOnSurface --------------- +============== .. class:: PointOnSurface(expression, **extra) @@ -362,7 +362,7 @@ Accepts a single geographic field or expression and returns a ``Point`` geometry guaranteed to lie on the surface of the field; otherwise returns ``None``. Reverse -------- +======= .. class:: Reverse(expression, **extra) @@ -372,7 +372,7 @@ Accepts a single geographic field or expression and returns a geometry with reversed coordinates. Scale ------ +===== .. class:: Scale(expression, x, y, z=0.0, **extra) @@ -383,7 +383,7 @@ scaled coordinates by multiplying them with the ``x``, ``y``, and optionally ``z`` parameters. SnapToGrid ----------- +========== .. class:: SnapToGrid(expression, *args, **extra) @@ -403,7 +403,7 @@ Number of Arguments Description =================== ===================================================== SymDifference -------------- +============= .. class:: SymDifference(expr1, expr2, **extra) @@ -418,7 +418,7 @@ parameters. MySQL support was added. Transform ---------- +========= .. class:: Transform(expression, srid, **extra) @@ -435,7 +435,7 @@ the transformed geometry to the spatial reference system specified by the are not necessarily the same as those used by PostGIS. Translate ---------- +========= .. class:: Translate(expression, x, y, z=0.0, **extra) @@ -446,7 +446,7 @@ its coordinates offset by the ``x``, ``y``, and optionally ``z`` numeric parameters. Union ------ +===== .. class:: Union(expr1, expr2, **extra) diff --git a/docs/ref/contrib/gis/install/geolibs.txt b/docs/ref/contrib/gis/install/geolibs.txt index 86a85cb05f..617d45f481 100644 --- a/docs/ref/contrib/gis/install/geolibs.txt +++ b/docs/ref/contrib/gis/install/geolibs.txt @@ -120,10 +120,10 @@ script, compile, and install:: $ cd .. Troubleshooting -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ Can't find GEOS library -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ When GeoDjango can't find GEOS, this error is raised: @@ -139,7 +139,7 @@ If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binut .. _geoslibrarypath: ``GEOS_LIBRARY_PATH`` -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ If your GEOS library is in a non-standard location, or you don't want to modify the system's library path then the :setting:`GEOS_LIBRARY_PATH` @@ -222,10 +222,10 @@ __ https://trac.osgeo.org/gdal/wiki/GdalOgrInPython .. _gdaltrouble: Troubleshooting -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ Can't find GDAL library -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag will be false: @@ -242,7 +242,7 @@ The solution is to properly configure your :ref:`libsettings` *or* set .. _gdallibrarypath: ``GDAL_LIBRARY_PATH`` -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ If your GDAL library is in a non-standard location, or you don't want to modify the system's library path then the :setting:`GDAL_LIBRARY_PATH` diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt index f30a3d74dc..cf49ca7de1 100644 --- a/docs/ref/contrib/gis/install/index.txt +++ b/docs/ref/contrib/gis/install/index.txt @@ -129,7 +129,7 @@ an environment variable, or by configuring the library path for the entire system. ``LD_LIBRARY_PATH`` environment variable -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A user may set this environment variable to customize the library paths they want to use. The typical library directory for software @@ -140,7 +140,7 @@ could place the following in their bash profile:: export LD_LIBRARY_PATH=/usr/local/lib 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``. @@ -160,7 +160,7 @@ modifying the system library path:: .. _binutils: Install ``binutils`` -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python module) to discover libraries. The ``find_library`` routine uses a program @@ -203,7 +203,7 @@ Foundation, however, this is not required. .. _macosx_python: Python -^^^^^^ +~~~~~~ Although OS X comes with Python installed, users can use `framework installers`__ provided by the Python Software Foundation. An advantage to @@ -223,7 +223,7 @@ __ https://www.python.org/ftp/python/ .. _postgresapp: Postgres.app -^^^^^^^^^^^^ +~~~~~~~~~~~~ `Postgres.app <http://postgresapp.com/>`_ is a standalone PostgreSQL server that includes the PostGIS extension. You will also need to install ``gdal`` and @@ -243,7 +243,7 @@ terminal prompt. .. _homebrew: Homebrew -^^^^^^^^ +~~~~~~~~ `Homebrew`__ provides "recipes" for building binaries and packages from source. It provides recipes for the GeoDjango prerequisites on Macintosh computers @@ -263,7 +263,7 @@ __ http://brew.sh/ .. _kyngchaos: 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 @@ -306,7 +306,7 @@ __ http://www.kyngchaos.com/software/postgres .. _psycopg2_kyngchaos: psycopg2 -~~~~~~~~ +^^^^^^^^ After you've installed the KyngChaos binaries and modified your ``PATH``, as described above, ``psycopg2`` may be installed using the following command:: @@ -334,7 +334,7 @@ __ http://pdb.finkproject.org/pdb/browse.php?summary=django-gis .. _macports: MacPorts -^^^^^^^^ +~~~~~~~~ `MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh computers running OS X. Because MacPorts still builds the software from source, @@ -379,7 +379,7 @@ GeoDjango on Windows. GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer. Python -^^^^^^ +~~~~~~ First, download the latest `Python 2.7 installer`__ from the Python website. Next, run the installer and keep the defaults -- for example, keep @@ -395,7 +395,7 @@ Next, run the installer and keep the defaults -- for example, keep __ https://python.org/download/ PostgreSQL -^^^^^^^^^^ +~~~~~~~~~~ First, download the latest `PostgreSQL 9.x installer`__ from the `EnterpriseDB`__ website. After downloading, simply run the installer, @@ -427,7 +427,7 @@ __ http://www.enterprisedb.com .. _postgisasb: PostGIS -^^^^^^^ +~~~~~~~ From within the Application Stack Builder (to run outside of the installer, :menuselection:`Start --> Programs --> PostgreSQL 9.x`), select @@ -446,7 +446,7 @@ default PostGIS database). password in the 'Database Connection Information' dialog. psycopg2 -^^^^^^^^ +~~~~~~~~ The ``psycopg2`` Python module provides the interface between Python and the PostgreSQL database. Download the latest `Windows installer`__ for your version @@ -457,7 +457,7 @@ __ http://www.stickpeople.com/projects/python/win-psycopg/ .. _osgeo4w: OSGeo4W -^^^^^^^ +~~~~~~~ The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS libraries required by GeoDjango. First, download the `OSGeo4W installer`_, @@ -471,7 +471,7 @@ installer. .. _OSGeo4W installer: https://trac.osgeo.org/osgeo4w/ Modify Windows environment -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to use GeoDjango, you will need to add your Python and OSGeo4W directories to your Windows system ``Path``, as well as create ``GDAL_DATA`` @@ -506,7 +506,7 @@ script, :download:`geodjango_setup.bat`. variables accordingly. Install Django and set up database -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Finally, :ref:`install Django <installing-official-release>` on your system. diff --git a/docs/ref/contrib/gis/install/spatialite.txt b/docs/ref/contrib/gis/install/spatialite.txt index d950472e8a..cf5710c395 100644 --- a/docs/ref/contrib/gis/install/spatialite.txt +++ b/docs/ref/contrib/gis/install/spatialite.txt @@ -20,13 +20,13 @@ __ http://www.gaia-gis.it/gaia-sins/ .. _spatialite_source: Installing from source -~~~~~~~~~~~~~~~~~~~~~~ +====================== :doc:`GEOS and PROJ.4</ref/contrib/gis/install/geolibs>` should be installed prior to building SpatiaLite. SQLite -^^^^^^ +------ Check first if SQLite is compiled with the `R*Tree module`__. Run the sqlite3 command line interface and enter the following query:: @@ -57,7 +57,7 @@ __ https://www.sqlite.org/download.html .. _spatialitebuild: SpatiaLite library (``libspatialite``) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------------- Get the latest SpatiaLite library source bundle from the `download page`__:: @@ -81,13 +81,13 @@ __ http://www.gaia-gis.it/gaia-sins/libspatialite-sources/ .. _spatialite_macosx: Mac OS X-specific instructions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================== To install the SpatiaLite library and tools, Mac OS X users can choose between :ref:`kyngchaos` and `Homebrew`_. KyngChaos -^^^^^^^^^ +--------- First, follow the instructions in the :ref:`kyngchaos` section. @@ -109,7 +109,7 @@ add the following to your ``settings.py``:: __ http://www.gaia-gis.it/spatialite-2.3.1/binaries.html Homebrew -^^^^^^^^ +-------- `Homebrew`_ handles all the SpatiaLite related packages on your behalf, including SQLite3, SpatiaLite, PROJ, and GEOS. Install them like this:: @@ -128,7 +128,7 @@ following to your ``settings.py``:: .. _create_spatialite_db: Creating a spatial database for SpatiaLite -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================================== When running ``manage.py migrate`` with a SQLite or SpatiaLite database, the database file will be automatically created if it doesn't exist. Django will diff --git a/docs/ref/contrib/gis/model-api.txt b/docs/ref/contrib/gis/model-api.txt index fccbdce35f..d5fe84ebd6 100644 --- a/docs/ref/contrib/gis/model-api.txt +++ b/docs/ref/contrib/gis/model-api.txt @@ -104,7 +104,7 @@ __ https://en.wikipedia.org/wiki/WGS84 .. _selecting-an-srid: 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 @@ -213,7 +213,7 @@ details. .. _geography-type: Geography Type -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ The geography type provides native support for spatial features represented with geographic coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_ diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt index 456f9c32b3..b50f276522 100644 --- a/docs/ref/contrib/gis/testing.txt +++ b/docs/ref/contrib/gis/testing.txt @@ -20,7 +20,7 @@ Settings .. setting:: POSTGIS_VERSION ``POSTGIS_VERSION`` -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ When GeoDjango's spatial backend initializes on PostGIS, it has to perform an SQL query to determine the version in order to figure out what @@ -43,7 +43,7 @@ only needs to have the ability to create databases. In other configurations, you may be required to use a database superuser. Create database user -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ To make a database user with the ability to create databases, use the following command:: @@ -59,7 +59,7 @@ Alternatively, you may alter an existing user's role from the SQL shell postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE; Create database superuser -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ This may be done at the time the user is created, for example:: diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 89365442c0..9a09c93774 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -695,7 +695,7 @@ GeoDjango extends :doc:`Django's admin application </ref/contrib/admin/index>` with support for editing geometry fields. Basics -^^^^^^ +~~~~~~ GeoDjango also supplements the Django admin by allowing users to create and modify geometries on a JavaScript slippy map (powered by `OpenLayers`_). @@ -742,7 +742,7 @@ position. .. _osmgeoadmin-intro: ``OSMGeoAdmin`` -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ With the :class:`~django.contrib.gis.admin.OSMGeoAdmin`, GeoDjango uses a `Open Street Map`_ layer in the admin. diff --git a/docs/ref/contrib/humanize.txt b/docs/ref/contrib/humanize.txt index 8accfe326e..66b15d70f3 100644 --- a/docs/ref/contrib/humanize.txt +++ b/docs/ref/contrib/humanize.txt @@ -16,7 +16,7 @@ filters. .. templatefilter:: apnumber apnumber --------- +======== For numbers 1-9, returns the number spelled out. Otherwise, returns the number. This follows Associated Press style. @@ -32,7 +32,7 @@ You can pass in either an integer or a string representation of an integer. .. templatefilter:: intcomma intcomma --------- +======== Converts an integer to a string containing commas every three digits. @@ -43,7 +43,7 @@ Examples: * ``450000`` becomes ``450,000``. * ``4500000`` becomes ``4,500,000``. -:ref:`Format localization <format-localization>` will be respected if enabled, +:doc:`/topics/i18n/formatting` will be respected if enabled, e.g. with the ``'de'`` language: * ``45000`` becomes ``'45.000'``. @@ -54,7 +54,7 @@ You can pass in either an integer or a string representation of an integer. .. templatefilter:: intword intword -------- +======= Converts a large integer to a friendly text representation. Works best for numbers over 1 million. @@ -67,7 +67,7 @@ Examples: Values up to 10^100 (Googol) are supported. -:ref:`Format localization <format-localization>` will be respected if enabled, +:doc:`/topics/i18n/formatting` will be respected if enabled, e.g. with the ``'de'`` language: * ``1000000`` becomes ``'1,0 Million'``. @@ -79,7 +79,7 @@ You can pass in either an integer or a string representation of an integer. .. templatefilter:: naturalday naturalday ----------- +========== For dates that are the current day or within one day, return "today", "tomorrow" or "yesterday", as appropriate. Otherwise, format the date using @@ -98,7 +98,7 @@ Examples (when 'today' is 17 Feb 2007): .. templatefilter:: naturaltime naturaltime ------------ +=========== For datetime values, returns a string representing how many seconds, minutes or hours ago it was -- falling back to the :tfilter:`timesince` @@ -130,7 +130,7 @@ Examples (when 'now' is 17 Feb 2007 16:30:00): .. templatefilter:: ordinal ordinal -------- +======= Converts an integer to its ordinal as a string. diff --git a/docs/ref/contrib/postgres/aggregates.txt b/docs/ref/contrib/postgres/aggregates.txt index d4c5f028f6..f9d222c930 100644 --- a/docs/ref/contrib/postgres/aggregates.txt +++ b/docs/ref/contrib/postgres/aggregates.txt @@ -19,17 +19,17 @@ These functions are described in more detail in the `PostgreSQL docs {'arr': [0, 1, 2]} General-purpose aggregation functions -------------------------------------- +===================================== ArrayAgg -~~~~~~~~ +-------- .. class:: ArrayAgg(expression, **extra) Returns a list of values, including nulls, concatenated into an array. BitAnd -~~~~~~ +------ .. class:: BitAnd(expression, **extra) @@ -37,7 +37,7 @@ BitAnd ``None`` if all values are null. BitOr -~~~~~ +----- .. class:: BitOr(expression, **extra) @@ -45,7 +45,7 @@ BitOr ``None`` if all values are null. BoolAnd -~~~~~~~~ +------- .. class:: BoolAnd(expression, **extra) @@ -53,7 +53,7 @@ BoolAnd null or if there are no values, otherwise ``False`` . BoolOr -~~~~~~ +------ .. class:: BoolOr(expression, **extra) @@ -61,7 +61,7 @@ BoolOr values are null or if there are no values, otherwise ``False``. StringAgg -~~~~~~~~~ +--------- .. class:: StringAgg(expression, delimiter) @@ -73,16 +73,16 @@ StringAgg Required argument. Needs to be a string. Aggregate functions for statistics ----------------------------------- +================================== ``y`` and ``x`` -~~~~~~~~~~~~~~~ +--------------- The arguments ``y`` and ``x`` for all these functions can be the name of a field or an expression returning a numeric data. Both are required. Corr -~~~~ +---- .. class:: Corr(y, x) @@ -90,7 +90,7 @@ Corr aren't any matching rows. CovarPop -~~~~~~~~ +-------- .. class:: CovarPop(y, x, sample=False) @@ -106,7 +106,7 @@ CovarPop population covariance. RegrAvgX -~~~~~~~~ +-------- .. class:: RegrAvgX(y, x) @@ -114,7 +114,7 @@ RegrAvgX ``float``, or ``None`` if there aren't any matching rows. RegrAvgY -~~~~~~~~ +-------- .. class:: RegrAvgY(y, x) @@ -122,7 +122,7 @@ RegrAvgY ``float``, or ``None`` if there aren't any matching rows. RegrCount -~~~~~~~~~ +--------- .. class:: RegrCount(y, x) @@ -130,7 +130,7 @@ RegrCount are not null. RegrIntercept -~~~~~~~~~~~~~ +------------- .. class:: RegrIntercept(y, x) @@ -139,7 +139,7 @@ RegrIntercept matching rows. RegrR2 -~~~~~~ +------ .. class:: RegrR2(y, x) @@ -147,7 +147,7 @@ RegrR2 ``None`` if there aren't any matching rows. RegrSlope -~~~~~~~~~ +--------- .. class:: RegrSlope(y, x) @@ -156,7 +156,7 @@ RegrSlope matching rows. RegrSXX -~~~~~~~ +------- .. class:: RegrSXX(y, x) @@ -164,7 +164,7 @@ RegrSXX variable) as a ``float``, or ``None`` if there aren't any matching rows. RegrSXY -~~~~~~~ +------- .. class:: RegrSXY(y, x) @@ -173,7 +173,7 @@ RegrSXY matching rows. RegrSYY -~~~~~~~ +------- .. class:: RegrSYY(y, x) @@ -181,7 +181,7 @@ RegrSYY variable) as a ``float``, or ``None`` if there aren't any matching rows. Usage examples --------------- +============== We will use this example table:: diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt index cb6f15acc5..af41666aa7 100644 --- a/docs/ref/contrib/postgres/fields.txt +++ b/docs/ref/contrib/postgres/fields.txt @@ -1,3 +1,4 @@ +================================ PostgreSQL specific model fields ================================ @@ -7,7 +8,7 @@ module. .. currentmodule:: django.contrib.postgres.fields ArrayField ----------- +========== .. class:: ArrayField(base_field, size=None, **options) @@ -91,7 +92,7 @@ ArrayField nullable and the values padded with ``None``. Querying ArrayField -^^^^^^^^^^^^^^^^^^^ +------------------- There are a number of custom lookups and transforms for :class:`ArrayField`. We will use the following example model:: @@ -242,7 +243,7 @@ lookups available after the transform do not change. For example:: fashion by Django. Indexing ArrayField -^^^^^^^^^^^^^^^^^^^ +------------------- At present using :attr:`~django.db.models.Field.db_index` will create a ``btree`` index. This does not offer particularly significant help to querying. @@ -250,7 +251,7 @@ A more useful index is a ``GIN`` index, which you should create using a :class:`~django.db.migrations.operations.RunSQL` operation. HStoreField ------------ +=========== .. class:: HStoreField(**options) @@ -292,7 +293,7 @@ HStoreField :class:`~django.contrib.postgres.validators.KeysValidator`. Querying HStoreField -^^^^^^^^^^^^^^^^^^^^ +-------------------- In addition to the ability to query by key, there are a number of custom lookups available for ``HStoreField``. @@ -457,7 +458,7 @@ using in conjunction with lookups on <QuerySet [<Dog: Meg>]> JSONField ---------- +========= .. versionadded:: 1.9 @@ -492,7 +493,7 @@ JSONField **As a result, this field requires PostgreSQL ≥ 9.4 and Psycopg2 ≥ 2.5.4**. Querying JSONField -^^^^^^^^^^^^^^^^^^ +------------------ We will use the following example model:: @@ -575,7 +576,7 @@ containment and keys with :class:`~django.contrib.postgres.fields.HStoreField`. .. _range-fields: Range Fields ------------- +============ There are five range field types, corresponding to the built-in range types in PostgreSQL. These fields are used to store a range of values; for example the @@ -588,7 +589,7 @@ information is necessary. The default is lower bound included, upper bound excluded. IntegerRangeField -^^^^^^^^^^^^^^^^^ +----------------- .. class:: IntegerRangeField(**options) @@ -598,7 +599,7 @@ IntegerRangeField Python. BigIntegerRangeField -^^^^^^^^^^^^^^^^^^^^ +-------------------- .. class:: BigIntegerRangeField(**options) @@ -608,7 +609,7 @@ BigIntegerRangeField Python. FloatRangeField -^^^^^^^^^^^^^^^ +--------------- .. class:: FloatRangeField(**options) @@ -617,7 +618,7 @@ FloatRangeField database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in Python. DateTimeRangeField -^^^^^^^^^^^^^^^^^^ +------------------ .. class:: DateTimeRangeField(**options) @@ -627,7 +628,7 @@ DateTimeRangeField Python. DateRangeField -^^^^^^^^^^^^^^ +-------------- .. class:: DateRangeField(**options) @@ -636,7 +637,7 @@ DateRangeField database and a :class:`~psycopg2:psycopg2.extras.DateRange` in Python. Querying Range Fields -^^^^^^^^^^^^^^^^^^^^^ +--------------------- There are a number of custom lookups and transforms for range fields. They are available on all the above fields, but we will use the following example @@ -675,7 +676,7 @@ operators ``@>``, ``<@``, and ``&&`` respectively. .. fieldlookup:: rangefield.contains contains -'''''''' +^^^^^^^^ >>> Event.objects.filter(ages__contains=NumericRange(4, 5)) <QuerySet [<Event: Soft play>]> @@ -683,7 +684,7 @@ contains .. fieldlookup:: rangefield.contained_by contained_by -'''''''''''' +^^^^^^^^^^^^ >>> Event.objects.filter(ages__contained_by=NumericRange(0, 15)) <QuerySet [<Event: Soft play>]> @@ -707,7 +708,7 @@ contained_by .. fieldlookup:: rangefield.overlap overlap -''''''' +^^^^^^^ >>> Event.objects.filter(ages__overlap=NumericRange(8, 12)) <QuerySet [<Event: Soft play>]> @@ -724,7 +725,7 @@ the specific range comparison operators. .. fieldlookup:: rangefield.fully_lt fully_lt -'''''''' +^^^^^^^^ The returned ranges are strictly less than the passed range. In other words, all the points in the returned range are less than all those in the passed @@ -736,7 +737,7 @@ range. .. fieldlookup:: rangefield.fully_gt fully_gt -'''''''' +^^^^^^^^ The returned ranges are strictly greater than the passed range. In other words, the all the points in the returned range are greater than all those in the @@ -748,7 +749,7 @@ passed range. .. fieldlookup:: rangefield.not_lt not_lt -'''''' +^^^^^^ The returned ranges do not contain any points less than the passed range, that is the lower bound of the returned range is at least the lower bound of the @@ -760,7 +761,7 @@ passed range. .. fieldlookup:: rangefield.not_gt not_gt -'''''' +^^^^^^ The returned ranges do not contain any points greater than the passed range, that is the upper bound of the returned range is at most the upper bound of the @@ -772,7 +773,7 @@ passed range. .. fieldlookup:: rangefield.adjacent_to adjacent_to -''''''''''' +^^^^^^^^^^^ The returned ranges share a bound with the passed range. @@ -788,7 +789,7 @@ lower or upper bound, or query based on emptiness. .. fieldlookup:: rangefield.startswith startswith -'''''''''' +^^^^^^^^^^ Returned objects have the given lower bound. Can be chained to valid lookups for the base field. @@ -799,7 +800,7 @@ for the base field. .. fieldlookup:: rangefield.endswith endswith -'''''''' +^^^^^^^^ Returned objects have the given upper bound. Can be chained to valid lookups for the base field. @@ -810,7 +811,7 @@ for the base field. .. fieldlookup:: rangefield.isempty isempty -''''''' +^^^^^^^ Returned objects are empty ranges. Can be chained to valid lookups for a :class:`~django.db.models.BooleanField`. diff --git a/docs/ref/contrib/postgres/forms.txt b/docs/ref/contrib/postgres/forms.txt index 431cf9c802..288c826f93 100644 --- a/docs/ref/contrib/postgres/forms.txt +++ b/docs/ref/contrib/postgres/forms.txt @@ -1,3 +1,4 @@ +=========================================== PostgreSQL specific form fields and widgets =========================================== @@ -6,6 +7,9 @@ All of these fields and widgets are available from the .. currentmodule:: django.contrib.postgres.forms +Fields +====== + SimpleArrayField ---------------- @@ -217,10 +221,10 @@ DateRangeField :class:`~django.contrib.postgres.fields.DateRangeField`. Widgets -------- +======= RangeWidget -~~~~~~~~~~~ +----------- .. class:: RangeWidget(base_widget, attrs=None) diff --git a/docs/ref/contrib/postgres/functions.txt b/docs/ref/contrib/postgres/functions.txt index f4abdc2c17..25dac99e4d 100644 --- a/docs/ref/contrib/postgres/functions.txt +++ b/docs/ref/contrib/postgres/functions.txt @@ -1,3 +1,4 @@ +====================================== PostgreSQL specific database functions ====================================== @@ -7,7 +8,7 @@ All of these functions are available from the .. currentmodule:: django.contrib.postgres.functions TransactionNow --------------- +============== .. class:: TransactionNow() diff --git a/docs/ref/contrib/postgres/index.txt b/docs/ref/contrib/postgres/index.txt index 29847c3f99..fe5b3be2ab 100644 --- a/docs/ref/contrib/postgres/index.txt +++ b/docs/ref/contrib/postgres/index.txt @@ -1,3 +1,4 @@ +=========================== ``django.contrib.postgres`` =========================== diff --git a/docs/ref/contrib/postgres/operations.txt b/docs/ref/contrib/postgres/operations.txt index 79c2021c39..81ecb6acb2 100644 --- a/docs/ref/contrib/postgres/operations.txt +++ b/docs/ref/contrib/postgres/operations.txt @@ -1,3 +1,4 @@ +============================= Database migration operations ============================= @@ -7,7 +8,7 @@ the ``django.contrib.postgres.operations`` module. .. currentmodule:: django.contrib.postgres.operations CreateExtension ---------------- +=============== .. class:: CreateExtension(name) @@ -18,7 +19,7 @@ CreateExtension This is a required argument. The name of the extension to be installed. HStoreExtension ---------------- +=============== .. class:: HStoreExtension() @@ -27,7 +28,7 @@ HStoreExtension connection to interpret hstore data. UnaccentExtension ------------------ +================= .. class:: UnaccentExtension() diff --git a/docs/ref/contrib/postgres/validators.txt b/docs/ref/contrib/postgres/validators.txt index f35a40dd27..21a1935f55 100644 --- a/docs/ref/contrib/postgres/validators.txt +++ b/docs/ref/contrib/postgres/validators.txt @@ -5,7 +5,7 @@ Validators .. module:: django.contrib.postgres.validators ``KeysValidator`` ------------------ +================= .. class:: KeysValidator(keys, strict=False, messages=None) @@ -20,7 +20,7 @@ Validators the value of a key is non-empty. Range validators ----------------- +================ .. class:: RangeMaxValueValidator(limit_value, message=None) diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index d6824af18c..6c9b93f1d6 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -1,3 +1,4 @@ +=================== The ``File`` object =================== @@ -7,7 +8,7 @@ for basic file handling in Django. .. currentmodule:: django.core.files The ``File`` Class ------------------- +================== .. class:: File(file_object) @@ -90,7 +91,7 @@ The ``File`` Class .. currentmodule:: django.core.files.base The ``ContentFile`` Class -------------------------- +========================= .. class:: ContentFile(File) @@ -107,7 +108,7 @@ The ``ContentFile`` Class .. currentmodule:: django.core.files.images The ``ImageFile`` Class ------------------------ +======================= .. class:: ImageFile(file_object) @@ -127,7 +128,7 @@ The ``ImageFile`` Class .. currentmodule:: django.core.files Additional methods on files attached to objects ------------------------------------------------ +=============================================== Any :class:`File` that is associated with an object (as with ``Car.photo``, below) will also have a couple of extra methods: diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt index be9c554341..6bbb197c0c 100644 --- a/docs/ref/files/storage.txt +++ b/docs/ref/files/storage.txt @@ -1,10 +1,11 @@ +================ File storage API ================ .. module:: django.core.files.storage Getting the current storage class ---------------------------------- +================================= Django provides two convenient ways to access the current storage class: @@ -27,7 +28,7 @@ Django provides two convenient ways to access the current storage class: raised if the import is unsuccessful. The FileSystemStorage Class ---------------------------- +=========================== .. class:: FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None) @@ -62,7 +63,7 @@ The FileSystemStorage Class an exception if the given file name does not exist. The Storage Class ------------------ +================= .. class:: Storage diff --git a/docs/ref/files/uploads.txt b/docs/ref/files/uploads.txt index 028e7a6875..9bc508781f 100644 --- a/docs/ref/files/uploads.txt +++ b/docs/ref/files/uploads.txt @@ -137,7 +137,7 @@ All file upload handlers should be subclasses of handlers wherever you wish. Required methods -~~~~~~~~~~~~~~~~ +---------------- Custom file upload handlers **must** define the following methods: @@ -171,7 +171,7 @@ Custom file upload handlers **must** define the following methods: the ``UploadedFile`` object should come from subsequent upload handlers. Optional methods -~~~~~~~~~~~~~~~~ +---------------- Custom upload handlers may also define any of the following optional methods or attributes: diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index c36f19ca2b..631fe1ea54 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -13,7 +13,7 @@ The Forms API .. _ref-forms-api-bound-unbound: Bound and unbound forms ------------------------ +======================= A :class:`Form` instance is either **bound** to a set of data, or **unbound**. @@ -69,7 +69,7 @@ another :class:`Form` instance. There is no way to change data in a should consider its data immutable, whether it has data or not. Using forms to validate data ----------------------------- +============================ .. method:: Form.clean() @@ -201,7 +201,7 @@ This includes ``ValidationError``\s that are raised in :meth:`Form.clean() "...") <django.forms.Form.add_error>`. Behavior of unbound forms -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- It's meaningless to validate a form with no data, but, for the record, here's what happens with unbound forms:: @@ -213,7 +213,7 @@ what happens with unbound forms:: {} Dynamic initial values ----------------------- +====================== .. attribute:: Form.initial @@ -249,7 +249,7 @@ precedence:: <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> Checking which form data has changed ------------------------------------- +==================================== .. method:: Form.has_changed() @@ -286,7 +286,7 @@ provided in :attr:`~Form.initial`. It returns an empty list if no data differs. ... print("The following fields changed: %s" % ", ".join(f.changed_data)) Accessing the fields from the form ----------------------------------- +================================== .. attribute:: Form.fields @@ -320,7 +320,7 @@ process:: '<tr><th>Username:</th><td><input name="name" type="text" value="class" /></td></tr>' Accessing "clean" data ----------------------- +====================== .. attribute:: Form.cleaned_data @@ -414,7 +414,7 @@ fields). More information about this is in :doc:`/ref/forms/validation`. .. _ref-forms-api-outputting-html: Outputting forms as HTML ------------------------- +======================== The second task of a ``Form`` object is to render itself as HTML. To do so, simply ``print`` it:: @@ -476,7 +476,7 @@ form, other output styles are available. Each style is available as a method on a form object, and each rendering method returns a Unicode object. ``as_p()`` -~~~~~~~~~~ +---------- .. method:: Form.as_p() @@ -493,7 +493,7 @@ containing one field:: <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p> ``as_ul()`` -~~~~~~~~~~~ +----------- .. method:: Form.as_ul() @@ -512,7 +512,7 @@ flexibility:: <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li> ``as_table()`` -~~~~~~~~~~~~~~ +-------------- .. method:: Form.as_table() @@ -532,7 +532,7 @@ it calls its ``as_table()`` method behind the scenes:: .. _ref-forms-api-styling-form-rows: Styling required or erroneous form rows -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------- .. attribute:: Form.error_css_class .. attribute:: Form.required_css_class @@ -571,7 +571,7 @@ classes, as needed. The HTML will look something like:: .. _ref-forms-api-configuring-label: Configuring form elements' HTML ``id`` attributes and ``<label>`` tags -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------------------------------------- .. attribute:: Form.auto_id @@ -693,7 +693,7 @@ using the ``label_suffix`` parameter to :meth:`~django.forms.BoundField.label_tag`. Notes on field ordering -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are displayed in the order in which you define them in your form class. For @@ -727,7 +727,7 @@ You may rearrange the fields any time using ``order_fields()`` with a list of field names as in :attr:`~django.forms.Form.field_order`. How errors are displayed -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ If you render a bound ``Form`` object, the act of rendering will automatically run the form's validation if it hasn't already happened, and the HTML output @@ -761,7 +761,7 @@ method you're using:: .. _ref-forms-error-list-format: Customizing the error list format -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- By default, forms use ``django.forms.utils.ErrorList`` to format validation errors. If you'd like to use an alternate class for displaying errors, you can @@ -785,7 +785,7 @@ Python 2):: <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p> More granular output --------------------- +==================== The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are simply shortcuts -- they're not the only way a form object can be displayed. @@ -824,7 +824,7 @@ The field-specific output honors the form object's ``auto_id`` setting:: <input type="text" name="message" id="id_message" /> Attributes of ``BoundField`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- .. attribute:: BoundField.data @@ -922,7 +922,7 @@ Attributes of ``BoundField`` message Methods of ``BoundField`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- .. method:: BoundField.as_hidden(attrs=None, **kwargs) @@ -995,7 +995,7 @@ Methods of ``BoundField`` hi Customizing ``BoundField`` --------------------------- +========================== .. versionadded:: 1.9 @@ -1039,7 +1039,7 @@ Now you can access the country in a template with .. _binding-uploaded-files: Binding uploaded files to a form --------------------------------- +================================ Dealing with forms that have ``FileField`` and ``ImageField`` fields is a little more complicated than a normal form. @@ -1080,7 +1080,7 @@ form data *and* file data:: >>> f = ContactFormWithMugshot() Testing for multipart forms -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- .. method:: Form.is_multipart() @@ -1103,7 +1103,7 @@ Here's an example of how you might use this in a template:: </form> Subclassing forms ------------------ +================= If you have multiple ``Form`` classes that share fields, you can use subclassing to remove redundancy. @@ -1164,7 +1164,7 @@ by setting the name of the field to ``None`` on the subclass. For example:: .. _form-prefix: Prefixes for forms ------------------- +================== .. attribute:: Form.prefix diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 99572497ca..38803df0f8 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -33,14 +33,14 @@ exception or returns the clean value:: .. _core-field-arguments: Core field arguments --------------------- +==================== Each ``Field`` class constructor takes at least these arguments. Some ``Field`` classes take additional, field-specific arguments, but the following should *always* be accepted: ``required`` -~~~~~~~~~~~~ +------------ .. attribute:: Field.required @@ -93,7 +93,7 @@ For other ``Field`` classes, it might be ``None``. (This varies from field to field.) ``label`` -~~~~~~~~~ +--------- .. attribute:: Field.label @@ -120,7 +120,7 @@ We've specified ``auto_id=False`` to simplify the output:: <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> ``label_suffix`` -~~~~~~~~~~~~~~~~ +---------------- .. attribute:: Field.label_suffix @@ -138,7 +138,7 @@ The ``label_suffix`` argument lets you override the form's <p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" /></p> ``initial`` -~~~~~~~~~~~ +----------- .. attribute:: Field.initial @@ -206,7 +206,7 @@ Instead of a constant, you can also pass any callable:: The callable will be evaluated only when the unbound form is displayed, not when it is defined. ``widget`` -~~~~~~~~~~ +---------- .. attribute:: Field.widget @@ -214,7 +214,7 @@ The ``widget`` argument lets you specify a ``Widget`` class to use when rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information. ``help_text`` -~~~~~~~~~~~~~ +------------- .. attribute:: Field.help_text @@ -253,7 +253,7 @@ fields. We've specified ``auto_id=False`` to simplify the output:: <p>Cc myself: <input type="checkbox" name="cc_myself" /></p> ``error_messages`` -~~~~~~~~~~~~~~~~~~ +------------------ .. attribute:: Field.error_messages @@ -280,7 +280,7 @@ In the `built-in Field classes`_ section below, each ``Field`` defines the error message keys it uses. ``validators`` -~~~~~~~~~~~~~~ +-------------- .. attribute:: Field.validators @@ -290,18 +290,18 @@ for this field. See the :doc:`validators documentation </ref/validators>` for more information. ``localize`` -~~~~~~~~~~~~ +------------ .. attribute:: Field.localize The ``localize`` argument enables the localization of form data input, as well as the rendered output. -See the :ref:`format localization <format-localization>` documentation for +See the :doc:`format localization </topics/i18n/formatting>` documentation for more information. ``disabled`` -~~~~~~~~~~~~ +------------ .. attribute:: Field.disabled @@ -313,10 +313,10 @@ Even if a user tampers with the field's value submitted to the server, it will be ignored in favor of the value from the form's initial data. Checking if the field data has changed --------------------------------------- +====================================== ``has_changed()`` -~~~~~~~~~~~~~~~~~~ +----------------- .. method:: Field.has_changed() @@ -328,7 +328,7 @@ See the :class:`Form.has_changed()` documentation for more information. .. _built-in-fields: Built-in ``Field`` classes --------------------------- +========================== Naturally, the ``forms`` library comes with a set of ``Field`` classes that represent common validation needs. This section documents each built-in field. @@ -338,7 +338,7 @@ For each field, we describe the default widget used if you don't specify (see the section on ``required`` above to understand what that means). ``BooleanField`` -~~~~~~~~~~~~~~~~ +---------------- .. class:: BooleanField(**kwargs) @@ -358,7 +358,7 @@ For each field, we describe the default widget used if you don't specify creating the ``BooleanField``. ``CharField`` -~~~~~~~~~~~~~ +------------- .. class:: CharField(**kwargs) @@ -385,7 +385,7 @@ For each field, we describe the default widget used if you don't specify trailing whitespace. ``ChoiceField`` -~~~~~~~~~~~~~~~ +--------------- .. class:: ChoiceField(**kwargs) @@ -410,7 +410,7 @@ For each field, we describe the default widget used if you don't specify callable, it is evaluated each time the field's form is initialized. ``TypedChoiceField`` -~~~~~~~~~~~~~~~~~~~~ +-------------------- .. class:: TypedChoiceField(**kwargs) @@ -442,7 +442,7 @@ For each field, we describe the default widget used if you don't specify accordingly. ``DateField`` -~~~~~~~~~~~~~ +------------- .. class:: DateField(**kwargs) @@ -478,10 +478,10 @@ For each field, we describe the default widget used if you don't specify '%d %B %Y', # '25 October 2006' '%d %B, %Y'] # '25 October, 2006' - See also :ref:`format localization <format-localization>`. + See also :doc:`format localization </topics/i18n/formatting>`. ``DateTimeField`` -~~~~~~~~~~~~~~~~~ +----------------- .. class:: DateTimeField(**kwargs) @@ -511,10 +511,10 @@ For each field, we describe the default widget used if you don't specify '%m/%d/%y %H:%M', # '10/25/06 14:30' '%m/%d/%y'] # '10/25/06' - See also :ref:`format localization <format-localization>`. + See also :doc:`format localization </topics/i18n/formatting>`. ``DecimalField`` -~~~~~~~~~~~~~~~~ +---------------- .. class:: DecimalField(**kwargs) @@ -552,7 +552,7 @@ For each field, we describe the default widget used if you don't specify The maximum number of decimal places permitted. ``DurationField`` -~~~~~~~~~~~~~~~~~ +----------------- .. class:: DurationField(**kwargs) @@ -567,7 +567,7 @@ For each field, we describe the default widget used if you don't specify :func:`~django.utils.dateparse.parse_duration`. ``EmailField`` -~~~~~~~~~~~~~~ +-------------- .. class:: EmailField(**kwargs) @@ -583,7 +583,7 @@ For each field, we describe the default widget used if you don't specify given length. ``FileField`` -~~~~~~~~~~~~~ +------------- .. class:: FileField(**kwargs) @@ -611,7 +611,7 @@ For each field, we describe the default widget used if you don't specify length and ``%(length)d`` will be replaced with the current filename length. ``FilePathField`` -~~~~~~~~~~~~~~~~~ +----------------- .. class:: FilePathField(**kwargs) @@ -654,7 +654,7 @@ For each field, we describe the default widget used if you don't specify ``FloatField`` -~~~~~~~~~~~~~~ +-------------- .. class:: FloatField(**kwargs) @@ -671,7 +671,7 @@ For each field, we describe the default widget used if you don't specify These control the range of values permitted in the field. ``ImageField`` -~~~~~~~~~~~~~~ +-------------- .. class:: ImageField(**kwargs) @@ -703,7 +703,7 @@ For each field, we describe the default widget used if you don't specify .. _Image: https://pillow.readthedocs.org/en/latest/reference/Image.html ``IntegerField`` -~~~~~~~~~~~~~~~~ +---------------- .. class:: IntegerField(**kwargs) @@ -727,7 +727,7 @@ For each field, we describe the default widget used if you don't specify These control the range of values permitted in the field. ``GenericIPAddressField`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- .. class:: GenericIPAddressField(**kwargs) @@ -762,7 +762,7 @@ For each field, we describe the default widget used if you don't specify when ``protocol`` is set to ``'both'``. ``MultipleChoiceField`` -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- .. class:: MultipleChoiceField(**kwargs) @@ -779,7 +779,7 @@ For each field, we describe the default widget used if you don't specify Takes one extra required argument, ``choices``, as for :class:`ChoiceField`. ``TypedMultipleChoiceField`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- .. class:: TypedMultipleChoiceField(**kwargs) @@ -801,7 +801,7 @@ For each field, we describe the default widget used if you don't specify :class:`TypedChoiceField`. ``NullBooleanField`` -~~~~~~~~~~~~~~~~~~~~ +-------------------- .. class:: NullBooleanField(**kwargs) @@ -811,7 +811,7 @@ For each field, we describe the default widget used if you don't specify * Validates nothing (i.e., it never raises a ``ValidationError``). ``RegexField`` -~~~~~~~~~~~~~~ +-------------- .. class:: RegexField(**kwargs) @@ -840,7 +840,7 @@ For each field, we describe the default widget used if you don't specify regex validation. ``SlugField`` -~~~~~~~~~~~~~ +------------- .. class:: SlugField(**kwargs) @@ -864,7 +864,7 @@ For each field, we describe the default widget used if you don't specify to ASCII letters. Defaults to ``False``. ``TimeField`` -~~~~~~~~~~~~~ +------------- .. class:: TimeField(**kwargs) @@ -888,7 +888,7 @@ For each field, we describe the default widget used if you don't specify '%H:%M', # '14:30' ``URLField`` -~~~~~~~~~~~~ +------------ .. class:: URLField(**kwargs) @@ -906,7 +906,7 @@ For each field, we describe the default widget used if you don't specify These are the same as ``CharField.max_length`` and ``CharField.min_length``. ``UUIDField`` -~~~~~~~~~~~~~ +------------- .. class:: UUIDField(**kwargs) @@ -919,10 +919,10 @@ For each field, we describe the default widget used if you don't specify to the :class:`~python:uuid.UUID` constructor. Slightly complex built-in ``Field`` classes -------------------------------------------- +=========================================== ``ComboField`` -~~~~~~~~~~~~~~ +-------------- .. class:: ComboField(**kwargs) @@ -950,7 +950,7 @@ Slightly complex built-in ``Field`` classes ValidationError: ['Ensure this value has at most 20 characters (it has 28).'] ``MultiValueField`` -~~~~~~~~~~~~~~~~~~~ +------------------- .. class:: MultiValueField(fields=(), **kwargs) @@ -1033,7 +1033,7 @@ Slightly complex built-in ``Field`` classes This method must be implemented in the subclasses. ``SplitDateTimeField`` -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- .. class:: SplitDateTimeField(**kwargs) @@ -1064,7 +1064,7 @@ Slightly complex built-in ``Field`` classes for :class:`TimeField` are used. Fields which handle relationships ---------------------------------- +================================= Two fields are available for representing relationships between models: :class:`ModelChoiceField` and @@ -1087,7 +1087,7 @@ method:: self.fields['foo_select'].queryset = ... ``ModelChoiceField`` -~~~~~~~~~~~~~~~~~~~~ +-------------------- .. class:: ModelChoiceField(**kwargs) @@ -1180,7 +1180,7 @@ method:: return "My Object #%i" % obj.id ``ModelMultipleChoiceField`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- .. class:: ModelMultipleChoiceField(**kwargs) @@ -1208,7 +1208,7 @@ method:: user's selection. Creating custom fields ----------------------- +====================== If the built-in ``Field`` classes don't meet your needs, you can easily create custom ``Field`` classes. To do this, just create a subclass of diff --git a/docs/ref/forms/formsets.txt b/docs/ref/forms/formsets.txt index 704a9bb198..144140c62e 100644 --- a/docs/ref/forms/formsets.txt +++ b/docs/ref/forms/formsets.txt @@ -12,4 +12,4 @@ Formset API reference. For introductory material about formsets, see the Returns a ``FormSet`` class for the given ``form`` class. - See :ref:`formsets` for example usage. + See :doc:`formsets </topics/forms/formsets>` for example usage. diff --git a/docs/ref/forms/models.txt b/docs/ref/forms/models.txt index 18ada3c776..b02cf9f1bd 100644 --- a/docs/ref/forms/models.txt +++ b/docs/ref/forms/models.txt @@ -61,8 +61,8 @@ Model Form API reference. For introductory material about model forms, see the Arguments ``formset``, ``extra``, ``max_num``, ``can_order``, ``can_delete`` and ``validate_max`` are passed through to - :func:`~django.forms.formsets.formset_factory`. See :ref:`formsets` for - details. + :func:`~django.forms.formsets.formset_factory`. See :doc:`formsets + </topics/forms/formsets>` for details. See :ref:`model-formsets` for example usage. diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index 7f334f4361..bb9a928c1a 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -1,10 +1,9 @@ -.. currentmodule:: django.forms - -.. _form-and-field-validation: - +========================= Form and field validation ========================= +.. currentmodule:: django.forms + Form validation happens when the data is cleaned. If you want to customize this process, there are various places to make changes, each one serving a different purpose. Three types of cleaning methods are run during form @@ -112,7 +111,7 @@ for all remaining fields are still executed. .. _raising-validation-error: Raising ``ValidationError`` ---------------------------- +=========================== In order to make error messages flexible and easy to override, consider the following guidelines: @@ -184,7 +183,7 @@ greatly benefit from fully featured ``ValidationError``\s (with a ``code`` name and a ``params`` dictionary). Raising multiple errors -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- If you detect multiple errors during a cleaning method and wish to signal all of them to the form submitter, it is possible to pass a list of errors to the @@ -206,7 +205,7 @@ with ``code``\s and ``params`` but a list of strings will also work:: ]) Using validation in practice ----------------------------- +============================ The previous sections explained how validation works in general for forms. Since it can sometimes be easier to put things into place by seeing each @@ -216,7 +215,7 @@ previous features. .. _validators: Using validators -~~~~~~~~~~~~~~~~ +---------------- Django's form (and model) fields support use of simple utility functions and classes known as validators. A validator is merely a callable object or @@ -254,7 +253,7 @@ argument being the pattern: ``^[-a-zA-Z0-9_]+$``. See the section on available and for an example of how to write a validator. Form field default cleaning -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- Let's first create a custom form field that validates its input is a string containing comma-separated email addresses. The full class looks like this:: @@ -300,7 +299,7 @@ method will be run as part of the cleaning process and it will, in turn, call the custom ``to_python()`` and ``validate()`` methods. Cleaning a specific field attribute -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------- Continuing on from the previous example, suppose that in our ``ContactForm``, we want to make sure that the ``recipients`` field always contains the address @@ -326,7 +325,7 @@ write a cleaning method that operates on the ``recipients`` field, like so:: .. _validating-fields-with-clean: Cleaning and validating fields that depend on each other -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------------------- Suppose we add another requirement to our contact form: if the ``cc_myself`` field is ``True``, the ``subject`` must contain the word ``"help"``. We are diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 092173cc7a..2d7a0f031d 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -22,7 +22,7 @@ dictionary that corresponds to the widget. .. _widget-to-field: Specifying widgets ------------------- +================== Whenever you specify a field on a form, Django will use a default widget that is appropriate to the type of data that is to be displayed. To find @@ -43,9 +43,8 @@ example:: This would specify a form with a comment that uses a larger :class:`Textarea` widget, rather than the default :class:`TextInput` widget. - Setting arguments for widgets ------------------------------ +============================= Many widgets have optional extra arguments; they can be set when defining the widget on the field. In the following example, the @@ -69,9 +68,8 @@ widget on the field. In the following example, the See the :ref:`built-in widgets` for more information about which widgets are available and which arguments they accept. - Widgets inheriting from the Select widget ------------------------------------------ +========================================= Widgets inheriting from the :class:`Select` widget deal with choices. They present the user with a list of options to choose from. The different widgets @@ -96,14 +94,13 @@ example:: >>> choice_field.widget.choices [('1', 'First and only')] - Widgets which offer a :attr:`~Select.choices` attribute can however be used with fields which are not based on choice -- such as a :class:`CharField` -- but it is recommended to use a :class:`ChoiceField`-based field when the choices are inherent to the model and not just the representational widget. Customizing widget instances ----------------------------- +============================ When Django renders a widget as HTML, it only renders very minimal markup - Django doesn't add class names, or any other widget-specific attributes. This @@ -116,7 +113,7 @@ There are two ways to customize widgets: :ref:`per widget instance .. _styling-widget-instances: Styling widget instances -^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ If you want to make one widget instance look different from another, you will need to specify additional attributes at the time when the widget object is @@ -167,7 +164,7 @@ You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See .. _styling-widget-classes: Styling widget classes -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- With widgets, it is possible to add assets (``css`` and ``javascript``) and more deeply customize their appearance and behavior. @@ -181,13 +178,16 @@ detail in the :doc:`Form Assets </topics/forms/media>` topic guide. .. _base-widget-classes: -Base Widget classes -------------------- +Base widget classes +=================== Base widget classes :class:`Widget` and :class:`MultiWidget` are subclassed by all the :ref:`built-in widgets <built-in widgets>` and may serve as a foundation for custom widgets. +``Widget`` +---------- + .. class:: Widget(attrs=None) This abstract class cannot be rendered, but provides the basic attribute @@ -257,6 +257,9 @@ foundation for custom widgets. customize it and add expensive processing, you should implement some caching mechanism yourself. +``MultiWidget`` +--------------- + .. class:: MultiWidget(widgets, attrs=None) A widget that is composed of multiple widgets. @@ -410,7 +413,7 @@ foundation for custom widgets. .. _built-in widgets: Built-in widgets ----------------- +================ Django provides a representation of all the basic HTML widgets, plus some commonly used groups of widgets in the ``django.forms.widgets`` module, @@ -421,7 +424,7 @@ and :ref:`handling of multi-valued input <composite-widgets>`. .. _text-widgets: Widgets handling input of text -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------ These widgets make use of the HTML elements ``input`` and ``textarea``. @@ -496,7 +499,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. If no ``format`` argument is provided, the default format is the first format found in :setting:`DATE_INPUT_FORMATS` and respects - :ref:`format-localization`. + :doc:`/topics/i18n/formatting`. ``DateTimeInput`` ~~~~~~~~~~~~~~~~~ @@ -513,7 +516,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. If no ``format`` argument is provided, the default format is the first format found in :setting:`DATETIME_INPUT_FORMATS` and respects - :ref:`format-localization`. + :doc:`/topics/i18n/formatting`. By default, the microseconds part of the time value is always set to ``0``. If microseconds are required, use a subclass with the @@ -534,7 +537,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. If no ``format`` argument is provided, the default format is the first format found in :setting:`TIME_INPUT_FORMATS` and respects - :ref:`format-localization`. + :doc:`/topics/i18n/formatting`. For the treatment of microseconds, see :class:`DateTimeInput`. @@ -548,7 +551,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. _selector-widgets: Selector and checkbox widgets -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------- ``CheckboxInput`` ~~~~~~~~~~~~~~~~~ @@ -712,7 +715,7 @@ When looping over the checkboxes, the ``label`` and ``input`` tags include .. _file-upload-widgets: File upload widgets -^^^^^^^^^^^^^^^^^^^ +------------------- ``FileInput`` ~~~~~~~~~~~~~ @@ -733,7 +736,7 @@ File upload widgets .. _composite-widgets: Composite widgets -^^^^^^^^^^^^^^^^^ +----------------- ``MultipleHiddenInput`` ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt index fc3f25dd29..abf5218437 100644 --- a/docs/ref/models/database-functions.txt +++ b/docs/ref/models/database-functions.txt @@ -24,7 +24,7 @@ allows the field to have two "empty values", but it's important for the ``Coalesce`` example below. Coalesce --------- +======== .. class:: Coalesce(*expressions, **extra) @@ -65,7 +65,7 @@ Usage examples:: >>> Coalesce('updated', now_sql) Concat ------- +====== .. class:: Concat(*expressions, **extra) @@ -92,7 +92,7 @@ Usage example:: Margaret Smith (Maggie) Greatest --------- +======== .. class:: Greatest(*expressions, **extra) @@ -136,7 +136,7 @@ and ``comment.modified``. a sensible minimum value to provide as a default. Least ------ +===== .. class:: Least(*expressions, **extra) @@ -160,7 +160,7 @@ will result in a database error. a sensible maximum value to provide as a default. Length ------- +====== .. class:: Length(expression, **extra) @@ -191,7 +191,7 @@ It can also be registered as a transform. For example:: The ability to register the function as a transform was added. Lower ------- +===== .. class:: Lower(expression, **extra) @@ -213,7 +213,7 @@ Usage example:: The ability to register the function as a transform was added. Now ---- +=== .. class:: Now() @@ -236,7 +236,7 @@ Usage example:: timestamp, use :class:`django.contrib.postgres.functions.TransactionNow`. Substr ------- +====== .. class:: Substr(expression, pos, length=None, **extra) @@ -255,7 +255,7 @@ Usage example:: marga Upper ------- +===== .. class:: Upper(expression, **extra) diff --git a/docs/ref/models/lookups.txt b/docs/ref/models/lookups.txt index eae0d2a5b3..0ac2d75ee5 100644 --- a/docs/ref/models/lookups.txt +++ b/docs/ref/models/lookups.txt @@ -31,7 +31,7 @@ A lookup expression consists of three parts: .. _lookup-registration-api: Registration API -~~~~~~~~~~~~~~~~ +================ Django uses :class:`~lookups.RegisterLookupMixin` to give a class the interface to register lookups on itself. The two prominent examples are @@ -75,7 +75,7 @@ follow this API. .. _query-expression: The Query Expression API -~~~~~~~~~~~~~~~~~~~~~~~~ +======================== The query expression API is a common set of methods that classes define to be usable in query expressions to translate themselves into SQL expressions. Direct @@ -118,7 +118,7 @@ following methods: be a :class:`~django.db.models.Field` instance. Transform reference -~~~~~~~~~~~~~~~~~~~ +=================== .. class:: Transform @@ -163,7 +163,7 @@ Transform reference its ``lhs.output_field``. Lookup reference -~~~~~~~~~~~~~~~~ +================ .. class:: Lookup diff --git a/docs/ref/models/meta.txt b/docs/ref/models/meta.txt index 1a28c4b741..dfb58b5e78 100644 --- a/docs/ref/models/meta.txt +++ b/docs/ref/models/meta.txt @@ -24,7 +24,7 @@ Field access API ================ Retrieving a single field instance of a model by name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------------------------- .. method:: Options.get_field(field_name) @@ -62,7 +62,7 @@ Retrieving a single field instance of a model by name FieldDoesNotExist: User has no field named 'does_not_exist' Retrieving all field instances of a model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------------- .. method:: Options.get_fields(include_parents=True, include_hidden=False) diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index e7ab608354..2014eb9b43 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -178,7 +178,7 @@ Related objects reference related manager's methods are disabled. Direct Assignment ------------------ +================= A related object set can be replaced in bulk with one operation by assigning a new iterable of objects to it:: diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index b5b2f621b4..bbc3ef063c 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -10,14 +10,14 @@ documentation for any custom tags or filters installed. .. _ref-templates-builtins-tags: Built-in tag reference ----------------------- +====================== .. highlight:: html+django .. templatetag:: autoescape autoescape -^^^^^^^^^^ +---------- Controls the current auto-escaping behavior. This tag takes either ``on`` or ``off`` as an argument and that determines whether auto-escaping is in effect @@ -41,7 +41,7 @@ Sample usage:: .. templatetag:: block block -^^^^^ +----- Defines a block that can be overridden by child templates. See :ref:`Template inheritance <template-inheritance>` for more information. @@ -49,7 +49,7 @@ Defines a block that can be overridden by child templates. See .. templatetag:: comment comment -^^^^^^^ +------- Ignores everything between ``{% comment %}`` and ``{% endcomment %}``. An optional note may be inserted in the first tag. For example, this is @@ -67,7 +67,7 @@ Sample usage:: .. templatetag:: csrf_token csrf_token -^^^^^^^^^^ +---------- This tag is used for CSRF protection, as described in the documentation for :doc:`Cross Site Request Forgeries </ref/csrf>`. @@ -75,7 +75,7 @@ This tag is used for CSRF protection, as described in the documentation for .. templatetag:: cycle cycle -^^^^^ +----- Produces one of its arguments each time this tag is encountered. The first argument is produced on the first encounter, the second argument on the second @@ -188,7 +188,7 @@ call to ``{% cycle %}`` doesn't specify ``silent``:: .. templatetag:: debug debug -^^^^^ +----- Outputs a whole load of debugging information, including the current context and imported modules. @@ -196,7 +196,7 @@ and imported modules. .. templatetag:: extends extends -^^^^^^^ +------- Signals that this template extends a parent template. @@ -215,7 +215,7 @@ See :ref:`template-inheritance` for more information. .. templatetag:: filter filter -^^^^^^ +------ Filters the contents of the block through one or more filters. Multiple filters can be specified with pipes and filters can have arguments, just as @@ -239,7 +239,7 @@ Sample usage:: .. templatetag:: firstof firstof -^^^^^^^ +------- Outputs the first argument variable that is not ``False``. Outputs nothing if all the passed variables are ``False``. @@ -283,7 +283,7 @@ output inside a variable. .. templatetag:: for for -^^^ +--- Loops over each item in an array, making the item available in a context variable. For example, to display a list of athletes provided in @@ -341,7 +341,7 @@ Variable Description ========================== =============================================== for ... empty -^^^^^^^^^^^^^ +------------- The ``for`` tag can take an optional ``{% empty %}`` clause whose text is displayed if the given array is empty or could not be found:: @@ -370,7 +370,7 @@ than -- the following:: .. templatetag:: if if -^^ +-- The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e. exists, is not empty, and is not a false boolean value) the contents of the @@ -392,7 +392,7 @@ clauses, as well as an ``{% else %}`` clause that will be displayed if all previous conditions fail. These clauses are optional. Boolean operators -""""""""""""""""" +~~~~~~~~~~~~~~~~~ :ttag:`if` tags may use ``and``, ``or`` or ``not`` to test a number of variables or to negate a given variable:: @@ -435,7 +435,7 @@ them to indicate precedence, you should use nested :ttag:`if` tags. ``<=``, ``>=`` and ``in`` which work as follows: ``==`` operator -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ Equality. Example:: @@ -444,7 +444,7 @@ Equality. Example:: {% endif %} ``!=`` operator -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ Inequality. Example:: @@ -454,7 +454,7 @@ Inequality. Example:: {% endif %} ``<`` operator -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ Less than. Example:: @@ -463,7 +463,7 @@ Less than. Example:: {% endif %} ``>`` operator -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ Greater than. Example:: @@ -472,7 +472,7 @@ Greater than. Example:: {% endif %} ``<=`` operator -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ Less than or equal to. Example:: @@ -481,7 +481,7 @@ Less than or equal to. Example:: {% endif %} ``>=`` operator -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ Greater than or equal to. Example:: @@ -490,7 +490,7 @@ Greater than or equal to. Example:: {% endif %} ``in`` operator -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ Contained within. This operator is supported by many Python containers to test whether the given value is in the container. The following are some examples @@ -511,7 +511,7 @@ of how ``x in y`` will be interpreted:: {% endif %} ``not in`` operator -~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^ Not contained within. This is the negation of the ``in`` operator. @@ -525,7 +525,7 @@ you should use:: {% if a > b and b > c %} Filters -""""""" +~~~~~~~ You can also use filters in the :ttag:`if` expression. For example:: @@ -534,7 +534,7 @@ You can also use filters in the :ttag:`if` expression. For example:: {% endif %} Complex expressions -""""""""""""""""""" +~~~~~~~~~~~~~~~~~~~ All of the above can be combined to form complex expressions. For such expressions, it can be important to know how the operators are grouped when the @@ -563,7 +563,7 @@ Sometimes that is better for clarity anyway, for the sake of those who do not know the precedence rules. ``ifequal`` and ``ifnotequal`` -"""""""""""""""""""""""""""""" +------------------------------ ``{% ifequal a b %} ... {% endifequal %}`` is an obsolete way to write ``{% if a == b %} ... {% endif %}``. Likewise, ``{% ifnotequal a b %} ... @@ -573,7 +573,7 @@ The ``ifequal`` and ``ifnotequal`` tags will be deprecated in a future release. .. templatetag:: ifchanged ifchanged -^^^^^^^^^ +--------- Check if a value has changed from the last iteration of a loop. @@ -618,7 +618,7 @@ will be displayed if the value has not changed:: .. templatetag:: include include -^^^^^^^ +------- Loads a template and renders it with the current context. This is a way of "including" other templates within a template. @@ -691,7 +691,7 @@ and returns an empty string. .. templatetag:: load load -^^^^ +---- Loads a custom template tag set. @@ -713,7 +713,7 @@ more information. .. templatetag:: lorem lorem -^^^^^ +----- Displays random "lorem ipsum" Latin text. This is useful for providing sample data in templates. @@ -747,7 +747,7 @@ Examples: .. templatetag:: now now -^^^ +--- Displays the current date and/or time, using a format according to the given string. Such string can contain format specifiers characters as described @@ -772,7 +772,7 @@ This would display as "It is the 4th of September". :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`, :setting:`SHORT_DATE_FORMAT` or :setting:`SHORT_DATETIME_FORMAT`. The predefined formats may vary depending on the current locale and - if :ref:`format-localization` is enabled, e.g.:: + if :doc:`/topics/i18n/formatting` is enabled, e.g.:: It is {% now "SHORT_DATETIME_FORMAT" %} @@ -786,7 +786,7 @@ output (as a string) inside a variable. This is useful if you want to use .. templatetag:: regroup regroup -^^^^^^^ +------- Regroups a list of alike objects by a common attribute. @@ -900,7 +900,7 @@ Another solution is to sort the data in the template using the {% regroup cities|dictsort:"country" by country as country_list %} Grouping on other properties -"""""""""""""""""""""""""""" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Any valid template lookup is a legal grouping attribute for the regroup tag, including methods, attributes, dictionary keys and list items. For @@ -922,7 +922,7 @@ attribute, allowing you to group on the display string rather than the .. templatetag:: spaceless spaceless -^^^^^^^^^ +--------- Removes whitespace between HTML tags. This includes tab characters and newlines. @@ -951,7 +951,7 @@ this example, the space around ``Hello`` won't be stripped:: .. templatetag:: templatetag templatetag -^^^^^^^^^^^ +----------- Outputs one of the syntax characters used to compose template tags. @@ -980,7 +980,7 @@ Sample usage:: .. templatetag:: url url -^^^ +--- Returns an absolute path reference (a URL without the domain name) matching a given view and optional parameters. Any special characters in the resulting @@ -1061,7 +1061,7 @@ by the context as to the current application. .. templatetag:: verbatim verbatim -^^^^^^^^ +-------- Stops the template engine from rendering the contents of this block tag. @@ -1082,7 +1082,7 @@ You can also designate a specific closing tag, allowing the use of .. templatetag:: widthratio widthratio -^^^^^^^^^^ +---------- For creating bar charts and such, this tag calculates the ratio of a given value to a maximum value, and then applies that ratio to a constant. @@ -1105,7 +1105,7 @@ variable. It can be useful, for instance, in a :ttag:`blocktrans` like this:: .. templatetag:: with with -^^^^ +---- Caches a complex variable under a simpler name. This is useful when accessing an "expensive" method (e.g., one that hits the database) multiple times. @@ -1131,12 +1131,12 @@ You can assign more than one context variable:: .. _ref-templates-builtins-filters: Built-in filter reference -------------------------- +========================= .. templatefilter:: add add -^^^ +--- Adds the argument to the value. @@ -1166,7 +1166,7 @@ output will be ``[1, 2, 3, 4, 5, 6]``. .. templatefilter:: addslashes addslashes -^^^^^^^^^^ +---------- Adds slashes before quotes. Useful for escaping strings in CSV, for example. @@ -1180,7 +1180,7 @@ If ``value`` is ``"I'm using Django"``, the output will be .. templatefilter:: capfirst capfirst -^^^^^^^^ +-------- Capitalizes the first character of the value. If the first character is not a letter, this filter has no effect. @@ -1194,7 +1194,7 @@ If ``value`` is ``"django"``, the output will be ``"Django"``. .. templatefilter:: center center -^^^^^^ +------ Centers the value in a field of a given width. @@ -1207,7 +1207,7 @@ If ``value`` is ``"Django"``, the output will be ``" Django "``. .. templatefilter:: cut cut -^^^ +--- Removes all values of arg from the given string. @@ -1221,7 +1221,7 @@ If ``value`` is ``"String with spaces"``, the output will be .. templatefilter:: date date -^^^^ +---- Formats a date according to the given format. @@ -1350,7 +1350,7 @@ representation of a ``datetime`` value. E.g.:: .. templatefilter:: default default -^^^^^^^ +------- If value evaluates to ``False``, uses the given default. Otherwise, uses the value. @@ -1364,7 +1364,7 @@ If ``value`` is ``""`` (the empty string), the output will be ``nothing``. .. templatefilter:: default_if_none default_if_none -^^^^^^^^^^^^^^^ +--------------- If (and only if) value is ``None``, uses the given default. Otherwise, uses the value. @@ -1381,7 +1381,7 @@ If ``value`` is ``None``, the output will be the string ``"nothing"``. .. templatefilter:: dictsort dictsort -^^^^^^^^ +-------- Takes a list of dictionaries and returns that list sorted by the key given in the argument. @@ -1435,7 +1435,7 @@ then the output would be:: .. templatefilter:: dictsortreversed dictsortreversed -^^^^^^^^^^^^^^^^ +---------------- Takes a list of dictionaries and returns that list sorted in reverse order by the key given in the argument. This works exactly the same as the above filter, @@ -1444,7 +1444,7 @@ but the returned value will be in reverse order. .. templatefilter:: divisibleby divisibleby -^^^^^^^^^^^ +----------- Returns ``True`` if the value is divisible by the argument. @@ -1457,7 +1457,7 @@ If ``value`` is ``21``, the output would be ``True``. .. templatefilter:: escape escape -^^^^^^ +------ Escapes a string's HTML. Specifically, it makes these replacements: @@ -1486,7 +1486,7 @@ For example, you can apply ``escape`` to fields when :ttag:`autoescape` is off:: .. templatefilter:: escapejs escapejs -^^^^^^^^ +-------- Escapes characters for use in JavaScript strings. This does *not* make the string safe for use in HTML, but does protect you from syntax errors when using @@ -1502,7 +1502,7 @@ the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u00 .. templatefilter:: filesizeformat filesizeformat -^^^^^^^^^^^^^^ +-------------- Formats the value like a 'human-readable' file size (i.e. ``'13 KB'``, ``'4.1 MB'``, ``'102 bytes'``, etc.). @@ -1524,7 +1524,7 @@ If ``value`` is 123456789, the output would be ``117.7 MB``. .. templatefilter:: first first -^^^^^ +----- Returns the first item in a list. @@ -1537,7 +1537,7 @@ If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``. .. templatefilter:: floatformat floatformat -^^^^^^^^^^^ +----------- When used without an argument, rounds a floating-point number to one decimal place -- but only if there's a decimal part to be displayed. For example: @@ -1590,7 +1590,7 @@ with an argument of ``-1``. .. templatefilter:: force_escape force_escape -^^^^^^^^^^^^ +------------ Applies HTML escaping to a string (see the :tfilter:`escape` filter for details). This filter is applied *immediately* and returns a new, escaped @@ -1608,7 +1608,7 @@ the :tfilter:`linebreaks` filter:: .. templatefilter:: get_digit get_digit -^^^^^^^^^ +--------- Given a whole number, returns the requested digit, where 1 is the right-most digit, 2 is the second-right-most digit, etc. Returns the original value for @@ -1624,7 +1624,7 @@ If ``value`` is ``123456789``, the output will be ``8``. .. templatefilter:: iriencode iriencode -^^^^^^^^^ +--------- Converts an IRI (Internationalized Resource Identifier) to a string that is suitable for including in a URL. This is necessary if you're trying to use @@ -1642,7 +1642,7 @@ If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&me=2"``. .. templatefilter:: join join -^^^^ +---- Joins a list with a string, like Python's ``str.join(list)`` @@ -1656,7 +1656,7 @@ If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string .. templatefilter:: last last -^^^^ +---- Returns the last item in a list. @@ -1670,7 +1670,7 @@ string ``"d"``. .. templatefilter:: length length -^^^^^^ +------ Returns the length of the value. This works for both strings and lists. @@ -1686,7 +1686,7 @@ The filter returns ``0`` for an undefined variable. .. templatefilter:: length_is length_is -^^^^^^^^^ +--------- Returns ``True`` if the value's length is the argument, or ``False`` otherwise. @@ -1700,7 +1700,7 @@ If ``value`` is ``['a', 'b', 'c', 'd']`` or ``"abcd"``, the output will be .. templatefilter:: linebreaks linebreaks -^^^^^^^^^^ +---------- Replaces line breaks in plain text with appropriate HTML; a single newline becomes an HTML line break (``<br />``) and a new line @@ -1716,7 +1716,7 @@ slug</p>``. .. templatefilter:: linebreaksbr linebreaksbr -^^^^^^^^^^^^ +------------ Converts all newlines in a piece of plain text to HTML line breaks (``<br />``). @@ -1731,7 +1731,7 @@ slug``. .. templatefilter:: linenumbers linenumbers -^^^^^^^^^^^ +----------- Displays text with line numbers. @@ -1754,7 +1754,7 @@ the output will be:: .. templatefilter:: ljust ljust -^^^^^ +----- Left-aligns the value in a field of a given width. @@ -1769,7 +1769,7 @@ If ``value`` is ``Django``, the output will be ``"Django "``. .. templatefilter:: lower lower -^^^^^ +----- Converts a string into all lowercase. @@ -1783,7 +1783,7 @@ If ``value`` is ``Totally LOVING this Album!``, the output will be .. templatefilter:: make_list make_list -^^^^^^^^^ +--------- Returns the value turned into a list. For a string, it's a list of characters. For an integer, the argument is cast into an unicode string before creating a @@ -1800,7 +1800,7 @@ list ``['1', '2', '3']``. .. templatefilter:: phone2numeric phone2numeric -^^^^^^^^^^^^^ +------------- Converts a phone number (possibly containing letters) to its numerical equivalent. @@ -1817,7 +1817,7 @@ If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``. .. templatefilter:: pluralize pluralize -^^^^^^^^^ +--------- Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'``. @@ -1848,14 +1848,14 @@ Example:: .. templatefilter:: pprint pprint -^^^^^^ +------ A wrapper around :func:`pprint.pprint` -- for debugging, really. .. templatefilter:: random random -^^^^^^ +------ Returns a random item from the given list. @@ -1868,7 +1868,7 @@ If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``. .. templatefilter:: rjust rjust -^^^^^ +----- Right-aligns the value in a field of a given width. @@ -1883,7 +1883,7 @@ If ``value`` is ``Django``, the output will be ``" Django"``. .. templatefilter:: safe safe -^^^^ +---- Marks a string as not requiring further HTML escaping prior to output. When autoescaping is off, this filter has no effect. @@ -1899,7 +1899,7 @@ autoescaping is off, this filter has no effect. .. templatefilter:: safeseq safeseq -^^^^^^^ +------- Applies the :tfilter:`safe` filter to each element of a sequence. Useful in conjunction with other filters that operate on sequences, such as @@ -1914,7 +1914,7 @@ individual elements of the sequence. .. templatefilter:: slice slice -^^^^^ +----- Returns a slice of the list. @@ -1931,7 +1931,7 @@ If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``. .. templatefilter:: slugify slugify -^^^^^^^ +------- Converts to ASCII. Converts spaces to hyphens. Removes characters that aren't alphanumerics, underscores, or hyphens. Converts to lowercase. Also strips @@ -1946,7 +1946,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``. .. templatefilter:: stringformat stringformat -^^^^^^^^^^^^ +------------ Formats the variable according to the argument, a string formatting specifier. This specifier uses Python string formatting syntax, with the exception that @@ -1964,7 +1964,7 @@ If ``value`` is ``10``, the output will be ``1.000000E+01``. .. templatefilter:: striptags striptags -^^^^^^^^^ +--------- Makes all possible efforts to strip all [X]HTML tags. @@ -1988,7 +1988,7 @@ output will be ``"Joel is a slug"``. .. templatefilter:: time time -^^^^ +---- Formats a time according to the given format. @@ -2034,7 +2034,7 @@ used, without applying any localization. .. templatefilter:: timesince timesince -^^^^^^^^^ +--------- Formats a date as the time since that date (e.g., "4 days, 6 hours"). @@ -2054,7 +2054,7 @@ date that is in the future relative to the comparison point. .. templatefilter:: timeuntil timeuntil -^^^^^^^^^ +--------- Similar to ``timesince``, except that it measures the time from now until the given date or datetime. For example, if today is 1 June 2006 and @@ -2075,7 +2075,7 @@ date that is in the past relative to the comparison point. .. templatefilter:: title title -^^^^^ +----- Converts a string into titlecase by making words start with an uppercase character and the remaining characters lowercase. This tag makes no effort to @@ -2090,7 +2090,7 @@ If ``value`` is ``"my FIRST post"``, the output will be ``"My First Post"``. .. templatefilter:: truncatechars truncatechars -^^^^^^^^^^^^^ +------------- Truncates a string if it is longer than the specified number of characters. Truncated strings will end with a translatable ellipsis sequence ("..."). @@ -2106,7 +2106,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel i..."``. .. templatefilter:: truncatechars_html truncatechars_html -^^^^^^^^^^^^^^^^^^ +------------------ Similar to :tfilter:`truncatechars`, except that it is aware of HTML tags. Any tags that are opened in the string and not closed before the truncation point @@ -2124,7 +2124,7 @@ Newlines in the HTML content will be preserved. .. templatefilter:: truncatewords truncatewords -^^^^^^^^^^^^^ +------------- Truncates a string after a certain number of words. @@ -2141,7 +2141,7 @@ Newlines within the string will be removed. .. templatefilter:: truncatewords_html truncatewords_html -^^^^^^^^^^^^^^^^^^ +------------------ Similar to :tfilter:`truncatewords`, except that it is aware of HTML tags. Any tags that are opened in the string and not closed before the truncation point, @@ -2162,7 +2162,7 @@ Newlines in the HTML content will be preserved. .. templatefilter:: unordered_list unordered_list -^^^^^^^^^^^^^^ +-------------- Recursively takes a self-nested list and returns an HTML unordered list -- WITHOUT opening and closing <ul> tags. @@ -2186,7 +2186,7 @@ contains ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then .. templatefilter:: upper upper -^^^^^ +----- Converts a string into all uppercase. @@ -2199,7 +2199,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``. .. templatefilter:: urlencode urlencode -^^^^^^^^^ +--------- Escapes a value for use in a URL. @@ -2224,7 +2224,7 @@ If ``value`` is ``"https://www.example.org/"``, the output will be .. templatefilter:: urlize urlize -^^^^^^ +------ Converts URLs and email addresses in text into clickable links. @@ -2268,7 +2268,7 @@ Django's built-in :tfilter:`escape` filter. The default value for .. templatefilter:: urlizetrunc urlizetrunc -^^^^^^^^^^^ +----------- Converts URLs and email addresses into clickable links just like urlize_, but truncates URLs longer than the given character limit. @@ -2289,7 +2289,7 @@ As with urlize_, this filter should only be applied to plain text. .. templatefilter:: wordcount wordcount -^^^^^^^^^ +--------- Returns the number of words. @@ -2302,7 +2302,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``4``. .. templatefilter:: wordwrap wordwrap -^^^^^^^^ +-------- Wraps words at specified line length. @@ -2321,7 +2321,7 @@ If ``value`` is ``Joel is a slug``, the output would be:: .. templatefilter:: yesno yesno -^^^^^ +----- Maps values for ``True``, ``False``, and (optionally) ``None``, to the strings "yes", "no", "maybe", or a custom mapping passed as a comma-separated list, and @@ -2343,14 +2343,14 @@ Value Argument Outputs ========== ====================== =========================================== Internationalization tags and filters -------------------------------------- +===================================== Django provides template tags and filters to control each aspect of :doc:`internationalization </topics/i18n/index>` in templates. They allow for granular control of translations, formatting, and time zone conversions. i18n -^^^^ +---- This library allows specifying translatable text in templates. To enable it, set :setting:`USE_I18N` to ``True``, then load it with @@ -2359,7 +2359,7 @@ To enable it, set :setting:`USE_I18N` to ``True``, then load it with See :ref:`specifying-translation-strings-in-template-code`. l10n -^^^^ +---- This library provides control over the localization of values in templates. You only need to load the library using ``{% load l10n %}``, but you'll often @@ -2368,7 +2368,7 @@ set :setting:`USE_L10N` to ``True`` so that localization is active by default. See :ref:`topic-l10n-templates`. tz -^^ +-- This library provides control over time zone conversions in templates. Like ``l10n``, you only need to load the library using ``{% load tz %}``, @@ -2378,25 +2378,25 @@ to local time happens by default. See :ref:`time-zones-in-templates`. Other tags and filters libraries --------------------------------- +================================ Django comes with a couple of other template-tag libraries that you have to enable explicitly in your :setting:`INSTALLED_APPS` setting and enable in your template with the :ttag:`{% load %}<load>` tag. django.contrib.humanize -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- A set of Django template filters useful for adding a "human touch" to data. See :doc:`/ref/contrib/humanize`. static -^^^^^^ +------ .. templatetag:: static static -"""""" +~~~~~~ To link to static files that are saved in :setting:`STATIC_ROOT` Django ships with a :ttag:`static` template tag. If the :mod:`django.contrib.staticfiles` @@ -2433,7 +2433,7 @@ slightly different call:: .. templatetag:: get_static_prefix get_static_prefix -""""""""""""""""" +~~~~~~~~~~~~~~~~~ You should prefer the :ttag:`static` template tag, but if you need more control over exactly where and how :setting:`STATIC_URL` is injected into the template, @@ -2454,7 +2454,7 @@ the value multiple times:: .. templatetag:: get_media_prefix get_media_prefix -"""""""""""""""" +~~~~~~~~~~~~~~~~ Similar to the :ttag:`get_static_prefix`, ``get_media_prefix`` populates a template variable with the media prefix :setting:`MEDIA_URL`, e.g.:: diff --git a/docs/ref/urlresolvers.txt b/docs/ref/urlresolvers.txt index 11c353502f..ecd5d6544d 100644 --- a/docs/ref/urlresolvers.txt +++ b/docs/ref/urlresolvers.txt @@ -11,7 +11,7 @@ to work until Django 2.0. reverse() ---------- +========= If you need to use something similar to the :ttag:`url` template tag in your code, Django provides the following function: @@ -81,7 +81,7 @@ use for reversing. By default, the root URLconf for the current thread is used. results. reverse_lazy() --------------- +============== A lazily evaluated version of `reverse()`_. @@ -101,7 +101,7 @@ URLConf is loaded. Some common cases where this function is necessary are: signature. resolve() ---------- +========= The ``resolve()`` function can be used for resolving URL paths to the corresponding view functions. It has the following signature: @@ -203,7 +203,7 @@ view would raise a ``Http404`` error before redirecting to it:: return response get_script_prefix() -------------------- +=================== .. function:: get_script_prefix() diff --git a/docs/ref/urls.txt b/docs/ref/urls.txt index 3420a41be4..75cc104383 100644 --- a/docs/ref/urls.txt +++ b/docs/ref/urls.txt @@ -5,7 +5,7 @@ .. module:: django.conf.urls static() --------- +======== .. function:: static.static(prefix, view=django.views.static.serve, **kwargs) @@ -19,7 +19,7 @@ Helper function to return a URL pattern for serving files in debug mode:: ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) url() ------ +===== .. function:: url(regex, view, kwargs=None, name=None) @@ -37,7 +37,7 @@ See :ref:`Naming URL patterns <naming-url-patterns>` for why the ``name`` parameter is useful. include() ---------- +========= .. function:: include(module, namespace=None, app_name=None) include(pattern_list) @@ -86,7 +86,7 @@ See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`. application namespace or remove the instance namespace. handler400 ----------- +========== .. data:: handler400 @@ -102,7 +102,7 @@ See the documentation about :ref:`the 400 (bad request) view <http_bad_request_view>` for more information. handler403 ----------- +========== .. data:: handler403 @@ -118,7 +118,7 @@ See the documentation about :ref:`the 403 (HTTP Forbidden) view <http_forbidden_view>` for more information. handler404 ----------- +========== .. data:: handler404 @@ -133,7 +133,7 @@ See the documentation about :ref:`the 404 (HTTP Not Found) view <http_not_found_view>` for more information. handler500 ----------- +========== .. data:: handler500 |