Add reference anchors to filter types to facilitate intersphinx refs (#1706)

* Update filterset.py

Remove the template_pack setter on rest_framework cripsy forms. This lets crispy forms decide what the template pack should be.

* add reference anchors to filter types in docs to facilitate intersphinx referencing

* replace section references with class references

* add osx DS_Store and _docs to gitignore

* go crazy with interpshinx references

Author: bckohan

.gitignore

@@ -12,3 +12,5 @@ docs/_build
 .idea
 .env
 .vscode
+_docs
+.DS_Store

docs/conf.py

@@ -28,7 +28,9 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = [
+    "sphinx.ext.intersphinx"
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -257,3 +259,15 @@
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 # texinfo_show_urls = 'footnote'
+
+
+intersphinx_mapping = {
+    "django": (
+        "https://docs.djangoproject.com/en/stable",
+        "https://docs.djangoproject.com/en/stable/_objects/",
+    ),
+    "python": ('https://docs.python.org/3', None)
+}
+
+# elide module names in class headings
+add_module_names = False

docs/guide/usage.txt

@@ -29,7 +29,7 @@ The filter
 ----------
 
 We have a number of fields and we want to let our users filter based on the
-name, the price or the release_date.  We create a ``FilterSet`` for this::
+name, the price or the release_date.  We create a :class:`~django_filters.filterset.FilterSet` for this::
 
     import django_filters
 
@@ -41,16 +41,17 @@ name, the price or the release_date.  We create a ``FilterSet`` for this::
             fields = ['price', 'release_date']
 
 
-As you can see this uses a very similar API to Django's ``ModelForm``.  Just
-like with a ``ModelForm`` we can also override filters, or add new ones using a
+As you can see this uses a very similar API to Django's :class:`~django.forms.ModelForm`. Just
+like with a :class:`~django.forms.ModelForm` we can also override filters, or add new ones using a
 declarative syntax.
 
 Declaring filters
 ~~~~~~~~~~~~~~~~~
 
 The declarative syntax provides you with the most flexibility when creating
 filters, however it is fairly verbose. We'll use the below example to outline
-the :ref:`core filter arguments <core-arguments>` on a ``FilterSet``::
+the :ref:`core filter arguments <core-arguments>` on a :class:`~django_filters.filterset.FilterSet`::
+
 
     class ProductFilter(django_filters.FilterSet):
         price = django_filters.NumberFilter()
@@ -72,18 +73,15 @@ There are two main arguments for filters:
 - ``field_name``: The name of the model field to filter on. You can traverse
   "relationship paths" using Django's ``__`` syntax to filter fields on a
   related model. ex, ``manufacturer__name``.
-- ``lookup_expr``: The `field lookup`_ to use when filtering. Django's ``__``
-  syntax can again be used in order to support lookup transforms.
-  ex, ``year__gte``.
+- ``lookup_expr``: The :ref:`field lookup <django:field-lookups>` to use when filtering.
+  Django's ``__`` syntax can again be used in order to support lookup transforms. ex, ``year__gte``.
 
 .. _`field lookup`: https://docs.djangoproject.com/en/stable/ref/models/querysets/#field-lookups
 
 Together, the field ``field_name`` and ``lookup_expr`` represent a complete Django
 lookup expression. A detailed explanation of lookup expressions is provided in
-Django's `lookup reference`_. django-filter supports expressions containing
-both transforms and a final lookup.
-
-.. _`lookup reference`: https://docs.djangoproject.com/en/stable/ref/models/lookups/#module-django.db.models.lookups
+Django's :mod:`lookup reference <django.db.models.lookups>`. django-filter supports
+expressions containing both transforms and a final lookup.
 
 
 Generating filters with Meta.fields
@@ -139,7 +137,7 @@ related model::
 Overriding default filters
 """"""""""""""""""""""""""
 
-Like ``django.contrib.admin.ModelAdmin``, it is possible to override
+Like :class:`django.contrib.admin.ModelAdmin`, it is possible to override
 default filters for all the models fields of the same kind using
 ``filter_overrides`` on the ``Meta`` class::
 
@@ -170,10 +168,10 @@ default filters for all the models fields of the same kind using
 Request-based filtering
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``FilterSet`` may be initialized with an optional ``request`` argument. If
-a request object is passed, then you may access the request during filtering.
-This allows you to filter by properties on the request, such as the currently
-logged-in user or the ``Accepts-Languages`` header.
+The :class:`~django_filters.filterset.FilterSet` may be initialized with an
+optional ``request`` argument. If a request object is passed, then you may access
+the request during filtering. This allows you to filter by properties on the request,
+such as the currently logged-in user or the ``Accepts-Languages`` header.
 
 .. note::
 
@@ -209,10 +207,11 @@ those that are published and those that are owned by the logged-in user
 Filtering the related queryset for ``ModelChoiceFilter``
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-The ``queryset`` argument for ``ModelChoiceFilter`` and ``ModelMultipleChoiceFilter``
-supports callable behavior. If a callable is passed, it will be invoked with the
-``request`` as its only argument. This allows you to perform the same kinds of
-request-based filtering without resorting to overriding ``FilterSet.__init__``.
+The ``queryset`` argument for :class:`~django_filters.filters.ModelChoiceFilter` and
+:class:`~django_filters.filters.ModelMultipleChoiceFilter` supports callable behavior.
+If a callable is passed, it will be invoked with the ``request`` as its only argument.
+This allows you to perform the same kinds of request-based filtering without resorting
+to overriding ``FilterSet.__init__``.
 
 .. code-block:: python
 
@@ -277,7 +276,9 @@ We need a URL pattern to call the view::
 The template
 ------------
 
-And lastly we need a template::
+And lastly we need a template:
+
+.. code-block:: django
 
     {% extends "base.html" %}
 

docs/ref/fields.txt

@@ -2,22 +2,23 @@
 Field Reference
 ===============
 
-``IsoDateTimeField``
-~~~~~~~~~~~~~~~~~~~~
+.. module:: django_filters.fields
+   :synopsis: Provided form fields and their arguments.
 
-Extends ``django.forms.DateTimeField`` to allow parsing ISO 8601 formated dates, in addition to existing formats
+.. currentmodule:: django_filters.fields
+
+.. class:: IsoDateTimeField
+
+Extends :class:`django.forms.DateTimeField` to allow parsing ISO 8601 formated dates, in addition to existing formats
 
 Defines a class level attribute ``ISO_8601`` as constant for the format.
 
 Sets ``input_formats = [ISO_8601]`` — this means that by default ``IsoDateTimeField`` will **only** parse ISO 8601 formated dates.
 
-You may set ``input_formats`` to your list of required formats as per the `DateTimeField Docs`_, using the ``ISO_8601`` class level attribute to specify the  ISO 8601 format.
+You may set :attr:`~django.forms.DateTimeField.input_formats` to your list of required formats as per the :class:`~django.forms.DateTimeField` docs, using the ``ISO_8601`` class level attribute to specify the ISO 8601 format.
 
 .. code-block:: python
 
     f = IsoDateTimeField()
     f.input_formats = [IsoDateTimeField.ISO_8601] + DateTimeField.input_formats
 
-
-.. _`DateTimeField Docs`: https://docs.djangoproject.com/en/stable/ref/forms/fields/#django.forms.DateTimeField.input_formats
-