Add Markdown linting for MkDocs documentation

[shyamkumaryadav]

I have going through all docs file find out lot's of issue

1. hard tab characters instead of using spaces for indentation
2. unordered list items using asterisk/dashes
3. different code block styles are used
4. link or image in a document not referenced or defined multiple times
5. table style also not same(docs: lint #8688 (comment))

[tomchristie]

Okay, let's deal with discussing these one at a time...

1. hard tab characters instead of using spaces for indentation

Yup agreed. We really don't want that. I was surprised to see that we've got several cases where that needs fixing up.

$ grep '\t' ./docs/*/*.md
./docs/api-guide/authentication.md:	from django.contrib.auth.models import User
./docs/api-guide/content-negotiation.md:	from myapp.negotiation import IgnoreClientContentNegotiation
./docs/api-guide/reverse.md:	from django.utils.timezone import now
./docs/api-guide/reverse.md:	class APIRootView(APIView):
./docs/api-guide/reverse.md:	    def get(self, request):
./docs/api-guide/reverse.md:	        year = now().year
./docs/api-guide/reverse.md:			data = {
./docs/api-guide/reverse.md: 				...
./docs/api-guide/reverse.md:    		    'year-summary-url': reverse('year-summary', args=[year], request=request)
./docs/api-guide/reverse.md:    		return Response(data)
./docs/api-guide/serializers.md:	    return Response(serializer.data)
./docs/api-guide/serializers.md:	    return Response(serializer.data)
./docs/api-guide/serializers.md:			# Return the validated values. This will be available as
./docs/api-guide/serializers.md:			# the `.validated_data` property.
./docs/api-guide/throttling.md:	from rest_framework.response import Response
./docs/api-guide/throttling.md:	from rest_framework.views import APIView
./docs/community/3.12-announcement.md:Method	                        | Path	          | Tags
./docs/community/3.12-announcement.md:`GET`, `PUT`, `PATCH`, `DELETE`	| `/users/{id}/`  | `['users']`
./docs/community/3.12-announcement.md:`GET`, `POST`                   |	`/users/`	      | `['users']`
./docs/community/3.12-announcement.md:`GET`, `PUT`, `PATCH`, `DELETE`	| `/orders/{id}/` | `['orders']`
./docs/community/3.12-announcement.md:`GET`, `POST`                   |	`/orders/`	    | `['orders']`

A pull request resolving all of those would be great, thanks.
I assume these should all be tabs->4 spaces, but I've not checked on the tables in the 3.12-announcement docs.

[tomchristie]

Okay, so now that #8692 is resolved, let's move onto...

2. unordered list items using asterisk/dashes

I think you're referring to an inconsistent usage of * for list items in some cases and - for list items in other cases.
Both are valid markdown, but yup it's neater if we're consistent throughout.

Which should we be using?...

$ grep  "^[*] " ./docs/*/*.md | wc -l
    1529
$ grep  "^[-] " ./docs/*/*.md | wc -l
      48

Okay, yup, let's switch up those - cases.

$ grep  "^[-] " ./docs/*/*.md 
./docs/api-guide/fields.md:- `max_length` - Validates that the input contains no more than this number of characters.
./docs/api-guide/fields.md:- `min_length` - Validates that the input contains no fewer than this number of characters.
./docs/api-guide/fields.md:- `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`.
./docs/api-guide/fields.md:- `trim_whitespace` - If set to `True` then leading and trailing whitespace is trimmed. Defaults to `True`.
./docs/api-guide/fields.md:- `format`: Determines the representation format of the uuid value
./docs/api-guide/fields.md:- `path` - The absolute filesystem path to a directory from which this FilePathField should get its choice.
./docs/api-guide/fields.md:- `match` - A regular expression, as a string, that FilePathField will use to filter filenames.
./docs/api-guide/fields.md:- `recursive` - Specifies whether all subdirectories of path should be included.  Default is `False`.
./docs/api-guide/fields.md:- `allow_files` - Specifies whether files in the specified location should be included. Default is `True`. Either this or `allow_folders` must be `True`.
./docs/api-guide/fields.md:- `allow_folders` - Specifies whether folders in the specified location should be included. Default is `False`. Either this or `allow_files` must be `True`.
./docs/api-guide/fields.md:- `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case insensitive.
./docs/api-guide/fields.md:- `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'.
./docs/api-guide/fields.md:- `max_value` Validate that the number provided is no greater than this value.
./docs/api-guide/fields.md:- `min_value` Validate that the number provided is no less than this value.
./docs/api-guide/fields.md:- `max_value` Validate that the number provided is no greater than this value.
./docs/api-guide/fields.md:- `min_value` Validate that the number provided is no less than this value.
./docs/api-guide/fields.md:- `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`.
./docs/api-guide/fields.md:- `decimal_places` The number of decimal places to store with the number.
./docs/api-guide/fields.md:- `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`.
./docs/api-guide/fields.md:- `max_value` Validate that the number provided is no greater than this value.
./docs/api-guide/fields.md:- `min_value` Validate that the number provided is no less than this value.
./docs/api-guide/fields.md:- `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.
./docs/api-guide/fields.md:- `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`.
./docs/api-guide/fields.md:- `max_value` Validate that the duration provided is no greater than this value.
./docs/api-guide/fields.md:- `min_value` Validate that the duration provided is no less than this value.
./docs/api-guide/fields.md:- `choices` - A list of valid values, or a list of `(key, display_name)` tuples.
./docs/api-guide/fields.md:- `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`.
./docs/api-guide/fields.md:- `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`.
./docs/api-guide/fields.md:- `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…"`
./docs/api-guide/fields.md:- `choices` - A list of valid values, or a list of `(key, display_name)` tuples.
./docs/api-guide/fields.md:- `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`.
./docs/api-guide/fields.md:- `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`.
./docs/api-guide/fields.md:- `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…"`
./docs/api-guide/fields.md:- `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.
./docs/api-guide/fields.md:- `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.
./docs/api-guide/fields.md:- `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.
./docs/api-guide/fields.md:- `allow_empty` - Designates if empty lists are allowed.
./docs/api-guide/fields.md:- `min_length` - Validates that the list contains no fewer than this number of elements.
./docs/api-guide/fields.md:- `max_length` - Validates that the list contains no more than this number of elements.
./docs/api-guide/fields.md:- `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.
./docs/api-guide/fields.md:- `allow_empty` - Designates if empty dictionaries are allowed.
./docs/api-guide/fields.md:- `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.
./docs/api-guide/fields.md:- `allow_empty` - Designates if empty dictionaries are allowed.
./docs/api-guide/fields.md:- `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`.
./docs/api-guide/fields.md:- `encoder` - Use this JSON encoder to serialize input object. Defaults to `None`.
./docs/api-guide/fields.md:- `method_name` - The name of the method on the serializer to be called. If not included this defaults to `get_<field_name>`.
./docs/api-guide/relations.md:- `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`.
./docs/api-guide/relations.md:- `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. Default

So a pull request editing fields.md and relations.md would be reasonable here.

[shyamkumaryadav]

Also Find Out that we are not using astricks in project-management.md is this file also need to update ?

[tomchristie]

Your decision

[shyamkumaryadav]

don't think it's required

[shyamkumaryadav]

3. different code block styles are used

I have open #8704

But in docs we use indented code block more

Indented Code Style 736

Fenced Code Style 43