maykinmedia · sergei-maertens · Jun 11, 2025 · Jun 5, 2025 · Jun 5, 2025
diff --git a/docs/index.rst b/docs/index.rst
@@ -46,15 +46,8 @@ Features
 
    quickstart
    apis
-   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

diff --git a/docs/maykin_common/settings.rst b/docs/maykin_common/settings.rst
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -1,18 +1,108 @@
+.. _quickstart:
+
 ==========
 Quickstart
 ==========
 
+maykin-common is based around the principle of "zero-cost" utilities and optional
+dependency groups. A barebones installation gives you some useful bits, but depending
+on you're project needs you likely want to install some extras.
+
+.. note:: A quick recap: extra's in python packages are additional labels you can
+   pass between square brackets to opt-in to additional dependencies, like so:
+
+   .. code-block:: bash
+
+      pip install maykin-common[extra1,extra2]
+
 Installation
 ============
 
-Install from PyPI with pip:
+You'll always want to install the base package, e.g.:
 
 .. code-block:: bash
 
     pip install maykin-common
 
+However, the usefulness increases with each extra. Each one of them is described below.
+
+.. tip:: default-project is pre-configured with the typical set of extras that apply
+   to the majority of projects:
+
+   .. code-block:: bash
+
+       pip install maykin-common[axes,mfa]
+
+MFA
+---
+
+Install command:
+
+.. code-block:: bash
+
+    pip install maykin-common[mfa]
+
+The MFA (multi-factor authentication) extra integrates
+`django-admin-index <https://pypi.org/project/django-admin-index>`_ and
+`maykin-2fa <https://pypi.org/project/maykin-2fa>`_. In particular, it controls the
+navigation menu when you're authenticated but not verified with your second factor yet.
+
+These packages and this extra are by default enabled in default-project.
+
+For more details, see :mod:`maykin_common.django_two_factor_auth`.
+
+Axes
+----
+
+Install command:
+
+.. code-block:: bash
+
+    pip install maykin-common[axes]
+
+Used for the throttling view mixins.
+
+`django-axes <https://pypi.org/project/django-axes>`_ is our standard solution to
+prevent brute forced logins and is included by default via default-project. It provides
+a helper to get the remote IP address of the person trying to log in, which is used in
+the throttling implementation.
+
+For more details, see :mod:`maykin_common.throttling`.
+
+.. _quickstart_pdf:
+
+PDF
+---
+
+Install command:
+
+.. code-block:: bash
+
+    pip install maykin-common[pdf]
+
+.. note:: You must define the setting ``PDF_BASE_URL_FUNCTION`` - a callable taking no
+   arguments that returns the absolute base URL where your site/project is running. It
+   is used to recognize references to your static assets (CSS and uploaded media).
+
+The PDF extra provides an easy to use template-based PDF generation helper, using
+`WeasyPrint <https://pypi.org/project/weasyprint>`_. It is optimized to load static
+assets (CSS/images/...) from disk rather than making network roundtrips.
+
+For details about the API, see :mod:`maykin_common.pdf`.
 
 Usage
 =====
 
-<document how to use the app here>
+All modules in maykin-common either only require Django to be available, or require some
+optional dependencies. Optional modules have zero footprint as long as you don't import
+them, and when you do use them, ensure you've installed the appropriate extra.
+
+API projects (team bron)
+------------------------
+
+For API projects, see TODO.
+
+Other
+-----
+
+See the reference documentation for details.
diff --git a/docs/maykin_common/checks.rst → docs/reference/checks.rst b/docs/maykin_common/checks.rst → docs/reference/checks.rst
diff --git a/docs/maykin_common/context_processors.rst → docs/reference/context_processors.rst b/docs/maykin_common/context_processors.rst → docs/reference/context_processors.rst
diff --git a/.../maykin_common/django_two_factor_auth.rst → docs/reference/django_two_factor_auth.rst b/.../maykin_common/django_two_factor_auth.rst → docs/reference/django_two_factor_auth.rst
diff --git a/docs/reference/index.rst b/docs/reference/index.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
diff --git a/docs/maykin_common/migration_operations.rst → docs/reference/migration_operations.rst b/docs/maykin_common/migration_operations.rst → docs/reference/migration_operations.rst
diff --git a/docs/maykin_common/pdf.rst → docs/reference/pdf.rst b/docs/maykin_common/pdf.rst → docs/reference/pdf.rst
diff --git a/docs/maykin_common/templatetags.rst → docs/reference/templatetags.rst b/docs/maykin_common/templatetags.rst → docs/reference/templatetags.rst
diff --git a/docs/maykin_common/throttling.rst → docs/reference/throttling.rst b/docs/maykin_common/throttling.rst → docs/reference/throttling.rst
diff --git a/docs/maykin_common/views.rst → docs/reference/views.rst b/docs/maykin_common/views.rst → docs/reference/views.rst
diff --git a/docs/settings.rst b/docs/settings.rst
@@ -0,0 +1,12 @@
+.. _settings:
+
+========
+Settings
+========
+
+maykin-common requires a number of settings to function properly. These settings are
+typically provided through default-project already.
+
+.. automodule:: maykin_common.settings
+    :members:
+    :undoc-members:
diff --git a/maykin_common/checks.py b/maykin_common/checks.py
@@ -1,3 +1,7 @@
+"""
+Custom Django system checks to prevent common mistakes.
+"""
+
 import os
 
 from django.conf import settings

diff --git a/maykin_common/django_two_factor_auth.py b/maykin_common/django_two_factor_auth.py
@@ -1,3 +1,9 @@
+"""
+Combine maykin-2fa and django-admin-index utilities.
+
+Depends on ``django-admin-index``.
+"""
+
 from django_admin_index.utils import (
     should_display_dropdown_menu as default_should_display_dropdown_menu,
 )

diff --git a/maykin_common/pdf.py b/maykin_common/pdf.py
@@ -9,6 +9,8 @@
 with a context into a PDF document (bytes output). You can use "external" stylesheets
 in these templates, and they will be resolved through django's staticfiles machinery
 by the custom :class:`UrlFetcher`.
+
+Depends on ``weasyprint``.
 """
 
 import logging

diff --git a/maykin_common/settings.py b/maykin_common/settings.py
@@ -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.
 """
 
 

diff --git a/maykin_common/throttling.py b/maykin_common/throttling.py
@@ -1,5 +1,7 @@
 """
 Provide mixins for throttling/rate limiting in views.
+
+Depends on ``django-axes``.
 """
 
 from collections.abc import Container