Ticket #14842: indent-options.diff

docs/ref/models/options.txt

@@ -6 +6 @@
 <meta-options>` that you can give your model in its internal ``class
 Meta``.
 
+Available ``Meta`` options
+==========================
+
+.. currentmodule:: django.db.models
+
+``abstract``
+------------
+
+.. attribute:: Options.abstract
+
+If ``True``, this model will be an :ref:`abstract base class <abstract-base-classes>`.
+
+``app_label``
+-------------
+
+.. attribute:: Options.app_label
+
+If a model exists outside of the standard :file:`models.py` (for instance, if
+the app's models are in submodules of ``myapp.models``), the model must define
+which app it is part of::
+
+    app_label = 'myapp'
+
+``db_table``
+------------
+
+.. attribute:: Options.db_table
+
+The name of the database table to use for the model::
+
+    db_table = 'music_album'
+
 .. _table-names:
 
 Table names
-===========
+~~~~~~~~~~~
 
 To save you time, Django automatically derives the name of the database table
 from the name of your model class and the app that contains it. A model's
 database table name is constructed by joining the model's "app label" -- the
-name you used in :djadmin:`manage.py startapp <startapp>` -- to the model's
-class name, with an underscore between them.
+name you used in ``manage.py startapp`` -- to the model's class name, with an
+underscore between them.
 
 For example, if you have an app ``bookstore`` (as created by
 ``manage.py startapp bookstore``), a model defined as ``class Book`` will have
@@ -28 +60 @@
 aren't allowed in Python variable names -- notably, the hyphen -- that's OK.
 Django quotes column and table names behind the scenes.
 
-Available ``Meta`` options
-==========================
-
-.. currentmodule:: django.db.models
-
-.. attribute:: Options.abstract
-
-    If ``True``, this model will be an
-    :ref:`abstract base class <abstract-base-classes>`.
-
-.. attribute:: Options.app_label
-
-    If a model exists outside of the standard :file:`models.py` (for instance,
-    if the app's models are in submodules of ``myapp.models``), the model must
-    define which app it is part of::
-
-        app_label = 'myapp'
-
-.. attribute:: Options.db_table
-
-    The name of the database table to use for the model::
-
-        db_table = 'music_album'
-
+``db_tablespace``
+-----------------
 
 .. attribute:: Options.db_tablespace
 
-    .. versionadded:: 1.0
+.. versionadded:: 1.0
+
+The name of the database tablespace to use for the model. If the backend doesn't
+support tablespaces, this option is ignored.
 
-    The name of the database tablespace to use for the model. If the backend
-    doesn't support tablespaces, this option is ignored.
+``get_latest_by``
+-----------------
 
 .. attribute:: Options.get_latest_by
 
-    The name of a :class:`DateField` or :class:`DateTimeField` in the model.
-    This specifies the default field to use in your model :class:`Manager`'s
-    :class:`~QuerySet.latest` method.
+The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
+specifies the default field to use in your model :class:`Manager`'s
+:class:`~QuerySet.latest` method.
 
-    Example::
+Example::
 
-        get_latest_by = "order_date"
+    get_latest_by = "order_date"
 
-    See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
+See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
+
+``managed``
+-----------------------
 
 .. attribute:: Options.managed
 
-    .. versionadded:: 1.1
+.. versionadded:: 1.1
+
+Defaults to ``True``, meaning Django will create the appropriate database
+tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
+management command. That is, Django *manages* the database tables' lifecycles.
 
-    Defaults to ``True``, meaning Django will create the appropriate database
-    tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
-    management command. That is, Django *manages* the database tables'
-    lifecycles.
+If ``False``, no database table creation or deletion operations will be
+performed for this model. This is useful if the model represents an existing
+table or a database view that has been created by some other means. This is
+the *only* difference when ``managed`` is ``False``. All other aspects of
+model handling are exactly the same as normal. This includes
 
-    If ``False``, no database table creation or deletion operations will be
-    performed for this model. This is useful if the model represents an
-    existing table or a database view that has been created by some other
-    means. This is the *only* difference when ``managed=False``. All other
-    aspects of model handling are exactly the same as normal. This includes:
+    1. Adding an automatic primary key field to the model if you don't declare
+       it.  To avoid confusion for later code readers, it's recommended to
+       specify all the columns from the database table you are modeling when
+       using unmanaged models.
 
-        1. Adding an automatic primary key field to the model if you don't
-           declare it.  To avoid confusion for later code readers, it's
-           recommended to specify all the columns from the database table you
-           are modeling when using unmanaged models.
+    2. If a model with ``managed=False`` contains a
+       :class:`~django.db.models.ManyToManyField` that points to another
+       unmanaged model, then the intermediate table for the many-to-many join
+       will also not be created. However, a the intermediary table between one
+       managed and one unmanaged model *will* be created.
 
-        2. If a model with ``managed=False`` contains a
-           :class:`~django.db.models.ManyToManyField` that points to another
-           unmanaged model, then the intermediate table for the many-to-many
-           join will also not be created. However, a the intermediary table
-           between one managed and one unmanaged model *will* be created.
+       If you need to change this default behavior, create the intermediary
+       table as an explicit model (with ``managed`` set as needed) and use the
+       :attr:`ManyToManyField.through` attribute to make the relation use your
+       custom model.
 
-           If you need to change this default behavior, create the intermediary
-           table as an explicit model (with ``managed`` set as needed) and use
-           the :attr:`~ManyToManyField.through` attribute to make the relation
-           use your custom model.
+For tests involving models with ``managed=False``, it's up to you to ensure
+the correct tables are created as part of the test setup.
 
-    For tests involving models with ``managed=False``, it's up to you to ensure
-    the correct tables are created as part of the test setup.
+If you're interested in changing the Python-level behavior of a model class,
+you *could* use ``managed=False`` and create a copy of an existing model.
+However, there's a better approach for that situation: :ref:`proxy-models`.
 
-    If you're interested in changing the Python-level behavior of a model class,
-    you *could* use ``managed=False`` and create a copy of an existing model.
-    However, there's a better approach for that situation: :ref:`proxy-models`.
+``order_with_respect_to``
+-------------------------
 
 .. attribute:: Options.order_with_respect_to
 
-    Marks this object as "orderable" with respect to the given field. This is
-    almost always used with related objects to allow them to be ordered with
-    respect to a parent object. For example, if an ``Answer`` relates to a
-    ``Question`` object, and a question has more than one answer, and the order
-    of answers matters, you'd do this::
+Marks this object as "orderable" with respect to the given field. This is almost
+always used with related objects to allow them to be ordered with respect to a
+parent object. For example, if an ``Answer`` relates to a ``Question`` object,
+and a question has more than one answer, and the order of answers matters, you'd
+do this::
+
+    class Answer(models.Model):
+        question = models.ForeignKey(Question)
+        # ...
 
-        class Answer(models.Model):
-            question = models.ForeignKey(Question)
-            # ...
+        class Meta:
+            order_with_respect_to = 'question'
 
-            class Meta:
-                order_with_respect_to = 'question'
+``ordering``
+------------
 
 .. attribute:: Options.ordering
 
-    The default ordering for the object, for use when obtaining lists of
-    objects::
+The default ordering for the object, for use when obtaining lists of objects::
 
-        ordering = ['-order_date']
+    ordering = ['-order_date']
 
-    This is a tuple or list of strings. Each string is a field name with an
-    optional "-" prefix, which indicates descending order. Fields without a
-    leading "-" will be ordered ascending. Use the string "?" to order
-    randomly.
+This is a tuple or list of strings. Each string is a field name with an optional
+"-" prefix, which indicates descending order. Fields without a leading "-" will
+be ordered ascending. Use the string "?" to order randomly.
 
-    .. note::
+.. note::
 
-        Regardless of how many fields are in :attr:`~Options.ordering`, the
-        admin site uses only the first field.
+    Regardless of how many fields are in :attr:`~Options.ordering`, the admin
+    site uses only the first field.
 
-    For example, to order by a ``pub_date`` field ascending, use this::
+For example, to order by a ``pub_date`` field ascending, use this::
 
-        ordering = ['pub_date']
+    ordering = ['pub_date']
 
-    To order by ``pub_date`` descending, use this::
+To order by ``pub_date`` descending, use this::
 
-        ordering = ['-pub_date']
+    ordering = ['-pub_date']
 
-    To order by ``pub_date`` descending, then by ``author`` ascending, use
-    this::
+To order by ``pub_date`` descending, then by ``author`` ascending, use this::
 
-        ordering = ['-pub_date', 'author']
+    ordering = ['-pub_date', 'author']
+
+``permissions``
+---------------
 
 .. attribute:: Options.permissions
 
-    Extra permissions to enter into the permissions table when creating this
-    object. Add, delete and change permissions are automatically created for
-    each object that has ``admin`` set. This example specifies an extra
-    permission, ``can_deliver_pizzas``::
+Extra permissions to enter into the permissions table when creating this object.
+Add, delete and change permissions are automatically created for each object
+that has ``admin`` set. This example specifies an extra permission,
+``can_deliver_pizzas``::
+
+    permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
 
-        permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
+This is a list or tuple of 2-tuples in the format ``(permission_code,
+human_readable_permission_name)``.
 
-    This is a list or tuple of 2-tuples in the format ``(permission_code,
-    human_readable_permission_name)``.
+``proxy``
+---------
 
 .. attribute:: Options.proxy
 
-    .. versionadded:: 1.1
+.. versionadded:: 1.1
+
+If set to ``True``, a model which subclasses another model will be treated as
+a :ref:`proxy model <proxy-models>`.
 
-    If set to ``True``, a model which subclasses another model will be treated
-    as a :ref:`proxy model <proxy-models>`.
+``unique_together``
+-------------------
 
 .. attribute:: Options.unique_together
 
-    Sets of field names that, taken together, must be unique::
+Sets of field names that, taken together, must be unique::
 
-        unique_together = (("driver", "restaurant"),)
+    unique_together = (("driver", "restaurant"),)
 
-    This is a list of lists of fields that must be unique when considered
-    together. It's used in the Django admin and is enforced at the database level
-    (i.e., the appropriate ``UNIQUE`` statements are included in the
-    ``CREATE TABLE`` statement).
+This is a list of lists of fields that must be unique when considered together.
+It's used in the Django admin and is enforced at the database level (i.e., the
+appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
+statement).
 
-    .. versionadded:: 1.0
+.. versionadded:: 1.0
 
-    For convenience, unique_together can be a single list when dealing with a
-    single set of fields::
+For convenience, unique_together can be a single list when dealing with a single
+set of fields::
 
-        unique_together = ("driver", "restaurant")
+    unique_together = ("driver", "restaurant")
+
+``verbose_name``
+----------------
 
 .. attribute:: Options.verbose_name
 
-    A human-readable name for the object, singular::
+A human-readable name for the object, singular::
+
+    verbose_name = "pizza"
 
-        verbose_name = "pizza"
+If this isn't given, Django will use a munged version of the class name:
+``CamelCase`` becomes ``camel case``.
 
-    If this isn't given, Django will use a munged version of the class name:
-    ``CamelCase`` becomes ``camel case``.
+``verbose_name_plural``
+-----------------------
 
 .. attribute:: Options.verbose_name_plural
 
-    The plural name for the object::
+The plural name for the object::
 
-        verbose_name_plural = "stories"
+    verbose_name_plural = "stories"
 
-    If this isn't given, Django will use
-    :attr:`~Options.verbose_name` + ``"s"``.
+If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.