Ticket #14842: indent-options4.diff

File indent-options4.diff, 15.1 KB (added by Adam Vandenberg, 15 years ago)

One more try

  • docs/ref/models/options.txt 

    diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
index 824dae2..4530439 100644
    a b Model ``Meta`` options  
    33======================
    44
    55This document explains all the possible :ref:`metadata options
    6 <meta-options>` that you can give your model in its internal ``class
    7 Meta``.
     6<meta-options>` that you can give your model in its internal
     7``class Meta``.
    88
    99Available ``Meta`` options
    1010==========================
    … … Available ``Meta`` options  
    1616
    1717.. attribute:: Options.abstract
    1818
    19 If ``True``, this model will be an :ref:`abstract base class <abstract-base-classes>`.
     19    If ``abstract = True``, this model will be an
     20    :ref:`abstract base class <abstract-base-classes>`.
    2021
    2122``app_label``
    2223-------------
    2324
    2425.. attribute:: Options.app_label
    2526
    26 If a model exists outside of the standard :file:`models.py` (for instance, if
    27 the app's models are in submodules of ``myapp.models``), the model must define
    28 which app it is part of::
     27    If a model exists outside of the standard :file:`models.py` (for instance,
     28    if the app's models are in submodules of ``myapp.models``), the model must
     29    define which app it is part of::
    2930
    30     app_label = 'myapp'
     31        app_label = 'myapp'
    3132
    3233``db_table``
    3334------------
    3435
    3536.. attribute:: Options.db_table
    3637
    37 The name of the database table to use for the model::
     38    The name of the database table to use for the model::
    3839
    39     db_table = 'music_album'
     40        db_table = 'music_album'
    4041
    4142.. _table-names:
    4243
    … … Table names  
    4647To save you time, Django automatically derives the name of the database table
    4748from the name of your model class and the app that contains it. A model's
    4849database table name is constructed by joining the model's "app label" -- the
    49 name you used in ``manage.py startapp`` -- to the model's class name, with an
    50 underscore between them.
     50name you used in :djadmin:`manage.py startapp <startapp>` -- to the model's
     51class name, with an underscore between them.
    5152
    5253For example, if you have an app ``bookstore`` (as created by
    5354``manage.py startapp bookstore``), a model defined as ``class Book`` will have
    … … Django quotes column and table names behind the scenes.  
    6566
    6667.. attribute:: Options.db_tablespace
    6768
    68 The name of the database tablespace to use for the model. If the backend doesn't
    69 support tablespaces, this option is ignored.
     69    The name of the database tablespace to use for the model. If the backend
     70    doesn't support tablespaces, this option is ignored.
    7071
    7172``get_latest_by``
    7273-----------------
    7374
    7475.. attribute:: Options.get_latest_by
    7576
    76 The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
    77 specifies the default field to use in your model :class:`Manager`'s
    78 :class:`~QuerySet.latest` method.
     77    The name of a :class:`DateField` or :class:`DateTimeField` in the model.
     78    This specifies the default field to use in your model :class:`Manager`'s
     79    :class:`~QuerySet.latest` method.
    7980
    80 Example::
     81    Example::
    8182
    82     get_latest_by = "order_date"
     83        get_latest_by = "order_date"
    8384
    84 See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
     85    See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
    8586
    8687``managed``
    87 -----------------------
     88-----------
    8889
    8990.. attribute:: Options.managed
    9091
    91 Defaults to ``True``, meaning Django will create the appropriate database
    92 tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
    93 management command. That is, Django *manages* the database tables' lifecycles.
     92    Defaults to ``True``, meaning Django will create the appropriate database
     93    tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
     94    management command. That is, Django *manages* the database tables' lifecycles.
    9495
    95 If ``False``, no database table creation or deletion operations will be
    96 performed for this model. This is useful if the model represents an existing
    97 table or a database view that has been created by some other means. This is
    98 the *only* difference when ``managed`` is ``False``. All other aspects of
    99 model handling are exactly the same as normal. This includes
     96    If ``False``, no database table creation or deletion operations will be
     97    performed for this model. This is useful if the model represents an existing
     98    table or a database view that has been created by some other means. This is
     99    the *only* difference when ``managed=False``. All other aspects of
     100    model handling are exactly the same as normal. This includes
    100101
    101     1. Adding an automatic primary key field to the model if you don't declare
    102        it.  To avoid confusion for later code readers, it's recommended to
    103        specify all the columns from the database table you are modeling when
    104        using unmanaged models.
     102        1. Adding an automatic primary key field to the model if you don't declare
     103           it.  To avoid confusion for later code readers, it's recommended to
     104           specify all the columns from the database table you are modeling when
     105           using unmanaged models.
    105106
    106     2. If a model with ``managed=False`` contains a
    107        :class:`~django.db.models.ManyToManyField` that points to another
    108        unmanaged model, then the intermediate table for the many-to-many join
    109        will also not be created. However, the intermediary table between one
    110        managed and one unmanaged model *will* be created.
     107        2. If a model with ``managed=False`` contains a
     108           :class:`~django.db.models.ManyToManyField` that points to another
     109           unmanaged model, then the intermediate table for the many-to-many join
     110           will also not be created. However, the intermediary table between one
     111           managed and one unmanaged model *will* be created.
    111112
    112        If you need to change this default behavior, create the intermediary
    113        table as an explicit model (with ``managed`` set as needed) and use the
    114        :attr:`ManyToManyField.through` attribute to make the relation use your
    115        custom model.
     113           If you need to change this default behavior, create the intermediary
     114           table as an explicit model (with ``managed`` set as needed) and use the
     115           :attr:`ManyToManyField.through` attribute to make the relation use your
     116           custom model.
    116117
    117 For tests involving models with ``managed=False``, it's up to you to ensure
    118 the correct tables are created as part of the test setup.
     118    For tests involving models with ``managed=False``, it's up to you to ensure
     119    the correct tables are created as part of the test setup.
    119120
    120 If you're interested in changing the Python-level behavior of a model class,
    121 you *could* use ``managed=False`` and create a copy of an existing model.
    122 However, there's a better approach for that situation: :ref:`proxy-models`.
     121    If you're interested in changing the Python-level behavior of a model class,
     122    you *could* use ``managed=False`` and create a copy of an existing model.
     123    However, there's a better approach for that situation: :ref:`proxy-models`.
    123124
    124125``order_with_respect_to``
    125126-------------------------
    126127
    127128.. attribute:: Options.order_with_respect_to
    128129
    129 Marks this object as "orderable" with respect to the given field. This is almost
    130 always used with related objects to allow them to be ordered with respect to a
    131 parent object. For example, if an ``Answer`` relates to a ``Question`` object,
    132 and a question has more than one answer, and the order of answers matters, you'd
    133 do this::
     130    Marks this object as "orderable" with respect to the given field. This is almost
     131    always used with related objects to allow them to be ordered with respect to a
     132    parent object. For example, if an ``Answer`` relates to a ``Question`` object,
     133    and a question has more than one answer, and the order of answers matters, you'd
     134    do this::
    134135
    135     class Answer(models.Model):
    136         question = models.ForeignKey(Question)
    137         # ...
     136        class Answer(models.Model):
     137            question = models.ForeignKey(Question)
     138            # ...
    138139
    139         class Meta:
    140             order_with_respect_to = 'question'
     140            class Meta:
     141                order_with_respect_to = 'question'
    141142
    142 When ``order_with_respect_to`` is set, two additional methods are provided to
    143 retrieve and to set the order of the related objects: ``get_RELATED_order()``
    144 and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For
    145 example, assuming that a ``Question`` object has multiple related ``Answer``
    146 objects, the list returned contains the primary keys of the related ``Answer``
    147 objects::
     143    When ``order_with_respect_to`` is set, two additional methods are provided to
     144    retrieve and to set the order of the related objects: ``get_RELATED_order()``
     145    and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For
     146    example, assuming that a ``Question`` object has multiple related ``Answer``
     147    objects, the list returned contains the primary keys of the related ``Answer``
     148    objects::
    148149
    149     >>> question = Question.objects.get(id=1)
    150     >>> question.get_answer_order()
    151     [1, 2, 3]
     150        >>> question = Question.objects.get(id=1)
     151        >>> question.get_answer_order()
     152        [1, 2, 3]
    152153
    153 The order of a ``Question`` object's related ``Answer`` objects can be set by
    154 passing in a list of ``Answer`` primary keys::
     154    The order of a ``Question`` object's related ``Answer`` objects can be set by
     155    passing in a list of ``Answer`` primary keys::
    155156
    156     >>> question.set_answer_order([3, 1, 2])
     157        >>> question.set_answer_order([3, 1, 2])
    157158
    158 The related objects also get two methods, ``get_next_in_order()`` and
    159 ``get_previous_in_order()``, which can be used to access those objects in their
    160 proper order. Assuming the ``Answer`` objects are ordered by ``id``::
     159    The related objects also get two methods, ``get_next_in_order()`` and
     160    ``get_previous_in_order()``, which can be used to access those objects in their
     161    proper order. Assuming the ``Answer`` objects are ordered by ``id``::
    161162
    162     >>> answer = Answer.objects.get(id=2)
    163     >>> answer.get_next_in_order()
    164     <Answer: 3>
    165     >>> answer.get_previous_in_order()
    166     <Answer: 1>
     163        >>> answer = Answer.objects.get(id=2)
     164        >>> answer.get_next_in_order()
     165        <Answer: 3>
     166        >>> answer.get_previous_in_order()
     167        <Answer: 1>
    167168
    168169``ordering``
    169170------------
    170171
    171172.. attribute:: Options.ordering
    172173
    173 The default ordering for the object, for use when obtaining lists of objects::
     174    The default ordering for the object, for use when obtaining lists of objects::
    174175
    175     ordering = ['-order_date']
     176        ordering = ['-order_date']
    176177
    177 This is a tuple or list of strings. Each string is a field name with an optional
    178 "-" prefix, which indicates descending order. Fields without a leading "-" will
    179 be ordered ascending. Use the string "?" to order randomly.
     178    This is a tuple or list of strings. Each string is a field name with an optional
     179    "-" prefix, which indicates descending order. Fields without a leading "-" will
     180    be ordered ascending. Use the string "?" to order randomly.
    180181
    181 .. note::
     182    .. note::
    182183
    183     Regardless of how many fields are in :attr:`~Options.ordering`, the admin
    184     site uses only the first field.
     184        Regardless of how many fields are in :attr:`~Options.ordering`, the admin
     185        site uses only the first field.
    185186
    186 For example, to order by a ``pub_date`` field ascending, use this::
     187    For example, to order by a ``pub_date`` field ascending, use this::
    187188
    188     ordering = ['pub_date']
     189        ordering = ['pub_date']
    189190
    190 To order by ``pub_date`` descending, use this::
     191    To order by ``pub_date`` descending, use this::
    191192
    192     ordering = ['-pub_date']
     193        ordering = ['-pub_date']
    193194
    194 To order by ``pub_date`` descending, then by ``author`` ascending, use this::
     195    To order by ``pub_date`` descending, then by ``author`` ascending, use this::
    195196
    196     ordering = ['-pub_date', 'author']
     197        ordering = ['-pub_date', 'author']
    197198
    198199``permissions``
    199200---------------
    200201
    201202.. attribute:: Options.permissions
    202203
    203 Extra permissions to enter into the permissions table when creating this object.
    204 Add, delete and change permissions are automatically created for each object
    205 that has ``admin`` set. This example specifies an extra permission,
    206 ``can_deliver_pizzas``::
     204    Extra permissions to enter into the permissions table when creating this object.
     205    Add, delete and change permissions are automatically created for each object
     206    that has ``admin`` set. This example specifies an extra permission,
     207    ``can_deliver_pizzas``::
    207208
    208     permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
     209        permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
    209210
    210 This is a list or tuple of 2-tuples in the format ``(permission_code,
    211 human_readable_permission_name)``.
     211    This is a list or tuple of 2-tuples in the format ``(permission_code,
     212    human_readable_permission_name)``.
    212213
    213214``proxy``
    214215---------
    215216
    216217.. attribute:: Options.proxy
    217218
    218 If set to ``True``, a model which subclasses another model will be treated as
    219 a :ref:`proxy model <proxy-models>`.
     219    If ``proxy = True``, a model which subclasses another model will be treated as
     220    a :ref:`proxy model <proxy-models>`.
    220221
    221222``unique_together``
    222223-------------------
    223224
    224225.. attribute:: Options.unique_together
    225226
    226 Sets of field names that, taken together, must be unique::
     227    Sets of field names that, taken together, must be unique::
    227228
    228     unique_together = (("driver", "restaurant"),)
     229        unique_together = (("driver", "restaurant"),)
    229230
    230 This is a list of lists of fields that must be unique when considered together.
    231 It's used in the Django admin and is enforced at the database level (i.e., the
    232 appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
    233 statement).
     231    This is a list of lists of fields that must be unique when considered together.
     232    It's used in the Django admin and is enforced at the database level (i.e., the
     233    appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
     234    statement).
    234235
    235 For convenience, unique_together can be a single list when dealing with a single
    236 set of fields::
     236    For convenience, unique_together can be a single list when dealing with a single
     237    set of fields::
    237238
    238     unique_together = ("driver", "restaurant")
     239        unique_together = ("driver", "restaurant")
    239240
    240241``verbose_name``
    241242----------------
    242243
    243244.. attribute:: Options.verbose_name
    244245
    245 A human-readable name for the object, singular::
     246    A human-readable name for the object, singular::
    246247
    247     verbose_name = "pizza"
     248        verbose_name = "pizza"
    248249
    249 If this isn't given, Django will use a munged version of the class name:
    250 ``CamelCase`` becomes ``camel case``.
     250    If this isn't given, Django will use a munged version of the class name:
     251    ``CamelCase`` becomes ``camel case``.
    251252
    252253``verbose_name_plural``
    253254-----------------------
    254255
    255256.. attribute:: Options.verbose_name_plural
    256257
    257 The plural name for the object::
     258    The plural name for the object::
    258259
    259     verbose_name_plural = "stories"
     260        verbose_name_plural = "stories"
    260261
    261 If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
     262    If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
Back to Top