Docs: use asterisk for unordered list (#8697)

docs/api-guide/fields.md

@@ -78,7 +78,7 @@ Defaults to `False`
 
 ### `source`
 
-The name of the attribute that will be used to populate the field.  May be a method that only takes a `self` argument, such as `URLField(source='get_absolute_url')`, or may use dotted notation to traverse attributes, such as `EmailField(source='user.email')`. 
+The name of the attribute that will be used to populate the field.  May be a method that only takes a `self` argument, such as `URLField(source='get_absolute_url')`, or may use dotted notation to traverse attributes, such as `EmailField(source='user.email')`.
 
 When serializing fields with dotted notation, it may be necessary to provide a `default` value if any object is not present or is empty during attribute traversal. Beware of possible n+1 problems when using source attribute if you are accessing a relational orm model. For example:
 
@@ -171,10 +171,10 @@ Corresponds to `django.db.models.fields.CharField` or `django.db.models.fields.T
 
 **Signature:** `CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)`
 
-- `max_length` - Validates that the input contains no more than this number of characters.
-- `min_length` - Validates that the input contains no fewer than this number of characters.
-- `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`.
-- `trim_whitespace` - If set to `True` then leading and trailing whitespace is trimmed. Defaults to `True`.
+* `max_length` - Validates that the input contains no more than this number of characters.
+* `min_length` - Validates that the input contains no fewer than this number of characters.
+* `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`.
+* `trim_whitespace` - If set to `True` then leading and trailing whitespace is trimmed. Defaults to `True`.
 
 The `allow_null` option is also available for string fields, although its usage is discouraged in favor of `allow_blank`. It is valid to set both `allow_blank=True` and `allow_null=True`, but doing so means that there will be two differing types of empty value permissible for string representations, which can lead to data inconsistencies and subtle application bugs.
 
@@ -222,11 +222,11 @@ A field that ensures the input is a valid UUID string. The `to_internal_value` m
 
 **Signature:** `UUIDField(format='hex_verbose')`
 
-- `format`: Determines the representation format of the uuid value
-    - `'hex_verbose'` - The canonical hex representation, including hyphens: `"5ce0e9a5-5ffa-654b-cee0-1238041fb31a"`
-    - `'hex'` - The compact hex representation of the UUID, not including hyphens: `"5ce0e9a55ffa654bcee01238041fb31a"`
-    - `'int'` - A 128 bit integer representation of the UUID: `"123456789012312313134124512351145145114"`
-    - `'urn'` - RFC 4122 URN representation of the UUID: `"urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a"`
+* `format`: Determines the representation format of the uuid value
+    * `'hex_verbose'` - The canonical hex representation, including hyphens: `"5ce0e9a5-5ffa-654b-cee0-1238041fb31a"`
+    * `'hex'` - The compact hex representation of the UUID, not including hyphens: `"5ce0e9a55ffa654bcee01238041fb31a"`
+    * `'int'` - A 128 bit integer representation of the UUID: `"123456789012312313134124512351145145114"`
+    * `'urn'` - RFC 4122 URN representation of the UUID: `"urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a"`
   Changing the `format` parameters only affects representation values. All formats are accepted by `to_internal_value`
 
 ## FilePathField
@@ -237,11 +237,11 @@ Corresponds to `django.forms.fields.FilePathField`.
 
 **Signature:** `FilePathField(path, match=None, recursive=False, allow_files=True, allow_folders=False, required=None, **kwargs)`
 
-- `path` - The absolute filesystem path to a directory from which this FilePathField should get its choice.
-- `match` - A regular expression, as a string, that FilePathField will use to filter filenames.
-- `recursive` - Specifies whether all subdirectories of path should be included.  Default is `False`.
-- `allow_files` - Specifies whether files in the specified location should be included. Default is `True`. Either this or `allow_folders` must be `True`.
-- `allow_folders` - Specifies whether folders in the specified location should be included. Default is `False`. Either this or `allow_files` must be `True`.
+* `path` - The absolute filesystem path to a directory from which this FilePathField should get its choice.
+* `match` - A regular expression, as a string, that FilePathField will use to filter filenames.
+* `recursive` - Specifies whether all subdirectories of path should be included.  Default is `False`.
+* `allow_files` - Specifies whether files in the specified location should be included. Default is `True`. Either this or `allow_folders` must be `True`.
+* `allow_folders` - Specifies whether folders in the specified location should be included. Default is `False`. Either this or `allow_files` must be `True`.
 
 ## IPAddressField
 
@@ -251,8 +251,8 @@ Corresponds to `django.forms.fields.IPAddressField` and `django.forms.fields.Gen
 
 **Signature**: `IPAddressField(protocol='both', unpack_ipv4=False, **options)`
 
-- `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case insensitive.
-- `unpack_ipv4` Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.
+* `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case insensitive.
+* `unpack_ipv4` Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.
 
 ---
 
@@ -266,8 +266,8 @@ Corresponds to `django.db.models.fields.IntegerField`, `django.db.models.fields.
 
 **Signature**: `IntegerField(max_value=None, min_value=None)`
 
-- `max_value` Validate that the number provided is no greater than this value.
-- `min_value` Validate that the number provided is no less than this value.
+* `max_value` Validate that the number provided is no greater than this value.
+* `min_value` Validate that the number provided is no less than this value.
 
 ## FloatField
 
@@ -277,8 +277,8 @@ Corresponds to `django.db.models.fields.FloatField`.
 
 **Signature**: `FloatField(max_value=None, min_value=None)`
 
-- `max_value` Validate that the number provided is no greater than this value.
-- `min_value` Validate that the number provided is no less than this value.
+* `max_value` Validate that the number provided is no greater than this value.
+* `min_value` Validate that the number provided is no less than this value.
 
 ## DecimalField
 
@@ -288,13 +288,13 @@ Corresponds to `django.db.models.fields.DecimalField`.
 
 **Signature**: `DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None)`
 
-- `max_digits` The maximum number of digits allowed in the number. It must be either `None` or an integer greater than or equal to `decimal_places`.
-- `decimal_places` The number of decimal places to store with the number.
-- `coerce_to_string` Set to `True` if string values should be returned for the representation, or `False` if `Decimal` objects should be returned. Defaults to the same value as the `COERCE_DECIMAL_TO_STRING` settings key, which will be `True` unless overridden. If `Decimal` objects are returned by the serializer, then the final output format will be determined by the renderer. Note that setting `localize` will force the value to `True`.
-- `max_value` Validate that the number provided is no greater than this value.
-- `min_value` Validate that the number provided is no less than this value.
-- `localize` Set to `True` to enable localization of input and output based on the current locale. This will also force `coerce_to_string` to `True`. Defaults to `False`. Note that data formatting is enabled if you have set `USE_L10N=True` in your settings file.
-- `rounding` Sets the rounding mode used when quantising to the configured precision. Valid values are [`decimal` module rounding modes][python-decimal-rounding-modes]. Defaults to `None`.
+* `max_digits` The maximum number of digits allowed in the number. It must be either `None` or an integer greater than or equal to `decimal_places`.
+* `decimal_places` The number of decimal places to store with the number.
+* `coerce_to_string` Set to `True` if string values should be returned for the representation, or `False` if `Decimal` objects should be returned. Defaults to the same value as the `COERCE_DECIMAL_TO_STRING` settings key, which will be `True` unless overridden. If `Decimal` objects are returned by the serializer, then the final output format will be determined by the renderer. Note that setting `localize` will force the value to `True`.
+* `max_value` Validate that the number provided is no greater than this value.
+* `min_value` Validate that the number provided is no less than this value.
+* `localize` Set to `True` to enable localization of input and output based on the current locale. This will also force `coerce_to_string` to `True`. Defaults to `False`. Note that data formatting is enabled if you have set `USE_L10N=True` in your settings file.
+* `rounding` Sets the rounding mode used when quantising to the configured precision. Valid values are [`decimal` module rounding modes][python-decimal-rounding-modes]. Defaults to `None`.
 
 #### Example usage
 
@@ -380,8 +380,8 @@ The representation is a string following this format `'[DD] [HH:[MM:]]ss[.uuuuuu
 
 **Signature:** `DurationField(max_value=None, min_value=None)`
 
-- `max_value` Validate that the duration provided is no greater than this value.
-- `min_value` Validate that the duration provided is no less than this value.
+* `max_value` Validate that the duration provided is no greater than this value.
+* `min_value` Validate that the duration provided is no less than this value.
 
 ---
 
@@ -395,10 +395,10 @@ Used by `ModelSerializer` to automatically generate fields if the corresponding
 
 **Signature:** `ChoiceField(choices)`
 
-- `choices` - A list of valid values, or a list of `(key, display_name)` tuples.
-- `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`.
-- `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to `None`.
-- `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"`
+* `choices` - A list of valid values, or a list of `(key, display_name)` tuples.
+* `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`.
+* `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to `None`.
+* `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"`
 
 Both the `allow_blank` and `allow_null` are valid options on `ChoiceField`, although it is highly recommended that you only use one and not both. `allow_blank` should be preferred for textual choices, and `allow_null` should be preferred for numeric or other non-textual choices.
 
@@ -408,10 +408,10 @@ A field that can accept a set of zero, one or many values, chosen from a limited
 
 **Signature:** `MultipleChoiceField(choices)`
 
-- `choices` - A list of valid values, or a list of `(key, display_name)` tuples.
-- `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`.
-- `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to `None`.
-- `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"`
+* `choices` - A list of valid values, or a list of `(key, display_name)` tuples.
+* `allow_blank` - If set to `True` then the empty string should be considered a valid value. If set to `False` then the empty string is considered invalid and will raise a validation error. Defaults to `False`.
+* `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to `None`.
+* `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"`
 
 As with `ChoiceField`, both the `allow_blank` and `allow_null` options are valid, although it is highly recommended that you only use one and not both. `allow_blank` should be preferred for textual choices, and `allow_null` should be preferred for numeric or other non-textual choices.
 
@@ -432,9 +432,9 @@ Corresponds to `django.forms.fields.FileField`.
 
 **Signature:** `FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)`
 
- - `max_length` - Designates the maximum length for the file name.
- - `allow_empty_file` - Designates if empty files are allowed.
-- `use_url` - If set to `True` then URL string values will be used for the output representation. If set to `False` then filename string values will be used for the output representation. Defaults to the value of the `UPLOADED_FILES_USE_URL` settings key, which is `True` unless set otherwise.
+* `max_length` - Designates the maximum length for the file name.
+* `allow_empty_file` - Designates if empty files are allowed.
+* `use_url` - If set to `True` then URL string values will be used for the output representation. If set to `False` then filename string values will be used for the output representation. Defaults to the value of the `UPLOADED_FILES_USE_URL` settings key, which is `True` unless set otherwise.
 
 ## ImageField
 
@@ -444,9 +444,9 @@ Corresponds to `django.forms.fields.ImageField`.
 
 **Signature:** `ImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)`
 
- - `max_length` - Designates the maximum length for the file name.
- - `allow_empty_file` - Designates if empty files are allowed.
-- `use_url` - If set to `True` then URL string values will be used for the output representation. If set to `False` then filename string values will be used for the output representation. Defaults to the value of the `UPLOADED_FILES_USE_URL` settings key, which is `True` unless set otherwise.
+* `max_length` - Designates the maximum length for the file name.
+* `allow_empty_file` - Designates if empty files are allowed.
+* `use_url` - If set to `True` then URL string values will be used for the output representation. If set to `False` then filename string values will be used for the output representation. Defaults to the value of the `UPLOADED_FILES_USE_URL` settings key, which is `True` unless set otherwise.
 
 Requires either the `Pillow` package or `PIL` package.  The `Pillow` package is recommended, as `PIL` is no longer actively maintained.
 
@@ -460,10 +460,10 @@ A field class that validates a list of objects.
 
 **Signature**: `ListField(child=<A_FIELD_INSTANCE>, allow_empty=True, min_length=None, max_length=None)`
 
-- `child` - A field instance that should be used for validating the objects in the list. If this argument is not provided then objects in the list will not be validated.
-- `allow_empty` - Designates if empty lists are allowed.
-- `min_length` - Validates that the list contains no fewer than this number of elements.
-- `max_length` - Validates that the list contains no more than this number of elements.
+* `child` - A field instance that should be used for validating the objects in the list. If this argument is not provided then objects in the list will not be validated.
+* `allow_empty` - Designates if empty lists are allowed.
+* `min_length` - Validates that the list contains no fewer than this number of elements.
+* `max_length` - Validates that the list contains no more than this number of elements.
 
 For example, to validate a list of integers you might use something like the following:
 
@@ -484,8 +484,8 @@ A field class that validates a dictionary of objects. The keys in `DictField` ar
 
 **Signature**: `DictField(child=<A_FIELD_INSTANCE>, allow_empty=True)`
 
-- `child` - A field instance that should be used for validating the values in the dictionary. If this argument is not provided then values in the mapping will not be validated.
-- `allow_empty` - Designates if empty dictionaries are allowed.
+* `child` - A field instance that should be used for validating the values in the dictionary. If this argument is not provided then values in the mapping will not be validated.
+* `allow_empty` - Designates if empty dictionaries are allowed.
 
 For example, to create a field that validates a mapping of strings to strings, you would write something like this:
 
@@ -502,8 +502,8 @@ A preconfigured `DictField` that is compatible with Django's postgres `HStoreFie
 
 **Signature**: `HStoreField(child=<A_FIELD_INSTANCE>, allow_empty=True)`
 
-- `child` - A field instance that is used for validating the values in the dictionary. The default child field accepts both empty strings and null values.
-- `allow_empty` - Designates if empty dictionaries are allowed.
+* `child` - A field instance that is used for validating the values in the dictionary. The default child field accepts both empty strings and null values.
+* `allow_empty` - Designates if empty dictionaries are allowed.
 
 Note that the child field **must** be an instance of `CharField`, as the hstore extension stores values as strings.
 
@@ -513,8 +513,8 @@ A field class that validates that the incoming data structure consists of valid
 
 **Signature**: `JSONField(binary, encoder)`
 
-- `binary` - If set to `True` then the field will output and validate a JSON encoded string, rather than a primitive data structure. Defaults to `False`.
-- `encoder` - Use this JSON encoder to serialize input object. Defaults to `None`.
+* `binary` - If set to `True` then the field will output and validate a JSON encoded string, rather than a primitive data structure. Defaults to `False`.
+* `encoder` - Use this JSON encoder to serialize input object. Defaults to `None`.
 
 ---
 
@@ -565,7 +565,7 @@ This is a read-only field. It gets its value by calling a method on the serializ
 
 **Signature**: `SerializerMethodField(method_name=None)`
 
-- `method_name` - The name of the method on the serializer to be called. If not included this defaults to `get_<field_name>`.
+* `method_name` - The name of the method on the serializer to be called. If not included this defaults to `get_<field_name>`.
 
 The serializer method referred to by the `method_name` argument should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. For example:
 

docs/api-guide/relations.md

@@ -33,7 +33,7 @@ For example, the following serializer would lead to a database hit each time eva
         class Meta:
             model = Album
             fields = ['album_name', 'artist', 'tracks']
-    
+
     # For each album object, tracks should be fetched from database
     qs = Album.objects.all()
     print(AlbumSerializer(qs, many=True).data)
@@ -278,7 +278,7 @@ This field is always read-only.
 
 As opposed to previously discussed _references_ to another entity, the referred entity can instead also be embedded or _nested_
 in the representation of the object that refers to it.
-Such nested relationships can be expressed by using serializers as fields. 
+Such nested relationships can be expressed by using serializers as fields.
 
 If the field is used to represent a to-many relationship, you should add the `many=True` flag to the serializer field.
 
@@ -494,8 +494,8 @@ This behavior is intended to prevent a template from being unable to render in a
 
 There are two keyword arguments you can use to control this behavior:
 
-- `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Set to `None` to disable any limiting. Defaults to `1000`.
-- `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"`
+* `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Set to `None` to disable any limiting. Defaults to `1000`.
+* `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"`
 
 You can also control these globally using the settings `HTML_SELECT_CUTOFF` and `HTML_SELECT_CUTOFF_TEXT`.