📝 Re-structure reference documentation

It's good practice to put the automatically generated documentation
in a 'reference' folder and apply a little bit of glue text to make
it easier to understand what is provided.

Author: sergei-maertens

docs/index.rst

@@ -45,15 +45,8 @@ Features
    :caption: Contents:
 
    quickstart
-   maykin_common/settings
-   maykin_common/checks
-   maykin_common/context_processors
-   maykin_common/django_two_factor_auth
-   maykin_common/migration_operations
-   maykin_common/throttling
-   maykin_common/pdf
-   maykin_common/views
-   maykin_common/templatetags
+   settings
+   reference/index
 
 
 Indices and tables

docs/maykin_common/settings.rst

@@ -1,3 +1,5 @@
+.. _quickstart:
+
 ==========
 Quickstart
 ==========
@@ -67,6 +69,8 @@ the throttling implementation.
 
 For more details, see :mod:`maykin_common.throttling`.
 
+.. _quickstart_pdf:
+
 PDF
 ---
 

docs/quickstart.rst

@@ -0,0 +1,35 @@
+.. _reference_index:
+
+=========
+Reference
+=========
+
+Python API reference.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Core utilities
+
+   checks
+   context_processors
+   migration_operations
+   views
+   templatetags
+
+.. toctree::
+   :maxdepth: 1
+   :caption: MFA
+
+   django_two_factor_auth
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Axes
+
+   throttling
+
+.. toctree::
+   :maxdepth: 1
+   :caption: PDF
+
+   pdf

docs/maykin_common/checks.rst renamed to docs/reference/checks.rst

@@ -0,0 +1,12 @@
+.. _settings:
+
+========
+Settings
+========
+
+maykin-common requires a number of settings to function properly. These settings are
+typically provides through default-project already.
+
+.. automodule:: maykin_common.settings
+    :members:
+    :undoc-members:

docs/maykin_common/context_processors.rst renamed to docs/reference/context_processors.rst

@@ -1,3 +1,7 @@
+"""
+Custom Django system checks to prevent common mistakes.
+"""
+
 import os
 
 from django.conf import settings

docs/maykin_common/django_two_factor_auth.rst renamed to docs/reference/django_two_factor_auth.rst

@@ -1,31 +1,46 @@
 from django.conf import settings
 
 GOOGLE_ANALYTICS_ID = None
-"""Google analytics id added to the request context"""
-
+"""
+Google analytics id added to the request context.
+"""
 
 SHOW_ENVIRONMENT = False
-"""enable or disable the `environment_info` template tag."""
+"""
+Enable or disable the ``{% environment_info %}`` template tag.
+"""
 
 ENVIRONMENT_BACKGROUND_COLOR = "orange"
-"""The background color of the `environment_info` template tag."""
+"""
+The background color of the ``{% environment_info %}`` template tag.
+"""
 
 ENVIRONMENT_FOREGROUND_COLOR = "black"
-"""The foreground color of the `environment_info` template tag."""
+"""
+The foreground color of the ``{% environment_info %}`` template tag.
+"""
 
 ENVIRONMENT_LABEL = None
-"""The foreground color of the `environment_info` template tag."""
+"""
+The textual content of the ``{% environment_info %}`` template tag.
+"""
 
 RELEASE = None
-"""The environment label shown in the `version_info` template tag."""
+"""
+The release version shown in the ``{% version_info %}`` template tag.
+"""
 
 GIT_SHA = None
-"""The git hash shown in the `version_info` template tag."""
+"""
+The commit hash shown in the ``{% version_info %}`` template tag.
+"""
 
 PDF_BASE_URL_FUNCTION = None
 """
 Function that returns the base url needed to download/resolve custom fonts and/or any
 image URLs included in the document to render.
+
+Required for the :ref:`quickstart_pdf` extra.
 """