docs: update docs

CHANGELOG

@@ -1,7 +1,7 @@
 Version 5.0 and newer
 ---------------------
 
-Please refer to the [GitHub Releases Page](https://github.com/stephenmcd/mezzanine/releases).
+Please refer to the `GitHub Releases Page <https://github.com/stephenmcd/mezzanine/releases>`_.
 
 Version 4.3.1 (Aug 08, 2018)
 ----------------------------
@@ -35,7 +35,7 @@ Version 4.3.0 (Jun 15, 2018)
   * Don't warn Mezzanine about itself - Stephen McDonald
   * Looser check for LocalMiddleware. Closes #1621 - Stephen McDonald
   * Modified the blog homepage pattern to a working version. Added import it requires - Ville Ranki
-  * Remove explicit ``show_banner`` argument from ``inner_run``. This broke --noreload for me. When called from ``https://github.com/django/django/blob/master/django/core/management/commands/runserver.py#L107``, if **options contains a ``show_banner`` arg (which, seemingly, is set just above in ``add_arguments)``, this throws a "Got multiple values for argument" TypeError - Kevin Shen
+  * Remove explicit ``show_banner`` argument from ``inner_run``. This broke --noreload for me. When called from ``https://github.com/django/django/blob/master/django/core/management/commands/runserver.py#L107``, if ``**options`` contains a ``show_banner`` arg (which, seemingly, is set just above in ``add_arguments``), this throws a "Got multiple values for argument" TypeError - Kevin Shen
   * Handle ``MIDDLEWARE_CLASSES`` -> MIDDLEWARE - Stephen McDonald
   * Don't use lazy static loading when Django's ManifestStaticFilesStorage is configured. Closes #1772 - Stephen McDonald
   * Link to Pillow docs for dependencies - Stephen McDonald

README.rst

@@ -1,7 +1,9 @@
 .. image:: https://img.shields.io/pypi/v/mezzanine.svg
    :target: https://pypi.org/project/mezzanine/
 .. image:: https://img.shields.io/pypi/pyversions/mezzanine.svg
+   :target: https://pypi.org/project/mezzanine/
 .. image:: https://img.shields.io/pypi/djversions/mezzanine.svg
+   :target: https://pypi.org/project/mezzanine/
 .. image:: https://github.com/stephenmcd/mezzanine/workflows/Test%20and%20release/badge.svg
    :target: https://github.com/stephenmcd/mezzanine/actions?query=workflow%3A%22Test+and+release%22
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
@@ -60,11 +62,9 @@ interface, Mezzanine provides the following:
 * `Search engine and API`_
 * Seamless integration with third-party Django apps
 * One step migration from other blogging engines
-* Automated production provisioning and deployments
 * `Disqus`_ integration, or built-in threaded comments
 * `Gravatar`_ integration
 * `Google Analytics`_ integration
-* `Twitter`_ feed integration
 * `bit.ly`_ integration
 * `Akismet`_ spam filtering
 * `JVM`_ compatible (via `Jython`_)
@@ -158,8 +158,6 @@ Quotes
 .. _`dashboard`: http://mezzanine.jupo.org/docs/admin-customization.html#dashboard
 .. _`Free Themes`: https://github.com/thecodinghouse/mezzanine-themes
 .. _`Premium Themes`: http://mezzathe.me/
-.. _`@abhinavsohani`: https://twitter.com/abhinavsohani
-.. _`@joshcartme`: https://twitter.com/joshcartme
 .. _`Custom templates`: http://mezzanine.jupo.org/docs/content-architecture.html#page-templates
 .. _`Multi-lingual sites`: http://mezzanine.jupo.org/docs/multi-lingual-sites.html
 .. _`JVM`: http://en.wikipedia.org/wiki/Java_virtual_machine
@@ -168,7 +166,6 @@ Quotes
 .. _`Disqus`: http://disqus.com/
 .. _`Gravatar`: http://gravatar.com/
 .. _`Google Analytics`: http://www.google.com/analytics/
-.. _`Twitter`: http://twitter.com/
 .. _`bit.ly`: http://bit.ly/
 .. _`Akismet`: http://akismet.com/
 .. _`GitHub`: http://github.com/stephenmcd/mezzanine/

docs/admin-customization.rst

@@ -2,8 +2,7 @@
 Admin Customization
 ===================
 
-Mezzanine uses the standard `Django admin interface
-<http://docs.djangoproject.com/en/dev/ref/contrib/admin/>`_ allowing you to
+Mezzanine uses :doc:`django:ref/contrib/admin/index` allowing you to
 add admin classes as you normally would with a Django project, but also
 provides the following enhancements to the admin interface that are
 configurable by the developer.
@@ -80,9 +79,22 @@ application which contains a named urlpattern ``fb_browse`` and is given
 the title ``Media Library`` to create a custom navigation item::
 
     ADMIN_MENU_ORDER = (
-        ("Content", ("pages.Page", "blog.BlogPost", "blog.Comment",
-            ("Media Library", "fb_browse"),)),
-        ("Site", ("auth.User", "auth.Group", "sites.Site", "redirects.Redirect")),
+        (
+            "Content", (
+                "pages.Page",
+                "blog.BlogPost",
+                "blog.Comment",
+                ("Media Library", "fb_browse"),
+            )
+        ),
+        (
+            "Site", (
+                "auth.User",
+                "auth.Group",
+                "sites.Site",
+                "redirects.Redirect",
+            )
+        ),
     )
 
 You can also use this two-item sequence approach for regular app/model
@@ -140,7 +152,7 @@ of TinyMCE, a different editor or even no editor at all.
 
     If you'd only like to customize the TinyMCE options specified in its
     JavaScript setup, you can do so via the :ref:`TINYMCE_SETUP_JS` setting
-    which lets you specify the URL to your own TinyMCE setup JavaScript
+    which lets you specify the path to your own TinyMCE setup JavaScript
     file.
 
 The default value for the :ref:`RICHTEXT_WIDGET_CLASS` setting is the

docs/caching-strategy.rst

@@ -9,15 +9,6 @@ that you wish to implement customized caching for your Mezzanine site.
 Mezzanine is preconfigured to cache aggressively when deployed to a
 production site with a cache backend installed.
 
-.. note::
-
-    By using Mezzanine's bundled deployment tools, Mezzanine's caching
-    will be properly configured and in use for your production site.
-    Consult the :doc:`deployment` section for more information. If you
-    would like to have a cache backend configured but to use a
-    different caching strategy, simply remove the cache middleware
-    described in the next section.
-
 Cache Middleware
 ================
 
@@ -60,12 +51,12 @@ sections might be anything that makes use of the current request
 object, including session-specific data.
 
 Accordingly, Mezzanine provides the start and end template tags
-:func:`.nevercache` and ``endnevercache``. Content wrapped in these tags
+``nevercache`` and ``endnevercache``. Content wrapped in these tags
 will not be cached. With two-phased
 rendering, the page is cached without any of the template code
-inside :func:`.nevercache` and ``endnevercache`` executed for the first
+inside ``nevercache`` and ``endnevercache`` executed for the first
 phase. The second phase then occurs after the page is retrieved from
-cache (or not), and any template code inside :func:`.nevercache` and
+cache (or not), and any template code inside ``nevercache`` and
 ``endnevercache`` is then executed.
 
 Mezzanine's two-phased rendering is based on Cody Soyland's
@@ -76,7 +67,7 @@ originally described the technique.
 
 .. note::
 
-    The template code inside :func:`.nevercache` and ``endnevercache`` will
+    The template code inside ``nevercache`` and ``endnevercache`` will
     only have access to template tags and variables provided by a
     normal request context, with the exception of any variables passed
     to the template from a view function. Variables added via context

docs/configuration.rst

@@ -54,9 +54,10 @@ page, we would define the following in ``authors.defaults``::
 .. note::
 
     If you are using Django 1.7 or greater and your app is included in your
-    INSTALLED_APPS as an AppConfig (eg authors.apps.MyCrazyConfig), Mezzanine
-    won't import your defaults.py automatically. Instead you must import it
-    manually in your AppConfig's ready() method.
+    :django:setting:`INSTALLED_APPS` as an ``AppConfig`` (eg
+    ``authors.apps.MyCustomConfig``), Mezzanine won't import your
+    ``defaults.py`` automatically. Instead you must import it manually in your
+    AppConfig's ``ready()`` method.
 
 Reading Settings
 ================
@@ -88,11 +89,9 @@ the website.
 
 .. note::
 
-    It's also important to realize that with any settings flagged as
-    editable, defining a value for these in your project's
-    ``settings.py`` will only serve to provide their default values.
-    Once editable settings are modified via the admin, their values
-    stored in the database will always be used.
+    It's also important to realize that with any settings flagged as editable,
+    defining a value for these in your project's ``settings.py`` will always
+    override the value stored in the database.
 
 Django Settings
 ===============

docs/frequently-asked-questions.rst

@@ -39,17 +39,17 @@ server  such as `Apache <http://httpd.apache.org/>`_ or `NGINX
 <http://nginx.org/>`_, will all be touched upon.
 
 Modifying the look and feel of a Mezzanine powered site requires at
-least an understanding of HTML, CSS and `Django's templating system
-<https://docs.djangoproject.com/en/dev/topics/templates/>`_.
+least an understanding of HTML, CSS and :doc:`Django's templating system
+<django:topics/templates>`.
 
 Extending Mezzanine by :ref:`creating-custom-content-types` or using
 additional Django apps, will require some knowledge of programming with
 `Python <http://python.org>`_, as well as a good understanding of
 Django's components, such as
-`models <https://docs.djangoproject.com/en/dev/topics/db/models/>`_,
-`views <https://docs.djangoproject.com/en/dev/topics/http/views/>`_,
-`urlpatterns <https://docs.djangoproject.com/en/dev/topics/http/urls/>`_
-and the `admin <https://docs.djangoproject.com/en/dev/ref/contrib/admin/>`_.
+:doc:`django:topics/db/models`,
+:doc:`django:topics/http/views`,
+:doc:`django:topics/http/urls`,
+and :doc:`django:ref/contrib/admin/index`.
 
 `Back to top <#>`_
 
@@ -58,8 +58,7 @@ and the `admin <https://docs.djangoproject.com/en/dev/ref/contrib/admin/>`_.
 Why aren't my JavaScript and CSS files showing up?
 --------------------------------------------------
 
-Mezzanine makes exclusive use of `Django's staticfiles app
-<https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/>`_,
+Mezzanine makes exclusive use of :doc:`django:ref/contrib/staticfiles`,
 for managing static files such as JavaScript, CSS, and images.
 
 When the :django:setting:`DEBUG` setting is set to ``True``, as it would be during

docs/index.rst

@@ -12,8 +12,7 @@ powered by Mezzanine <http://mezzanine.jupo.org/sites/>`_.
     A working knowledge of `Django <https://www.djangoproject.com/>`_
     is required to work with Mezzanine and the documentation assumes as
     much. If you're new to Django, you'll need to work through the
-    `Django tutorial
-    <https://docs.djangoproject.com/en/dev/intro/tutorial01/>`_
+    :doc:`Django tutorial <django:intro/tutorial01>`
     before being able to understand the concepts used throughout the
     Mezzanine documentation. *A mantra for working with Mezzanine:
     Mezzanine Is Just Django* - `Ken Bolton <http://bscientific.org/>`_,

docs/model-customization.rst

@@ -84,10 +84,10 @@ migrations management commands included in Django starting from
 version 1.7. In the first example above, Django's ``makemigrations``
 command views the new ``image`` field on the
 :class:`.BlogPost` model of the :mod:`mezzanine.blog` app. As such, in order to
-create a migration for it, the migration must be created for the blog
+create a migration for it, the migration must be created for the ``blog``
 app itself and by default would end up in the migrations directory of
-the blog app, which completely goes against the notion of not
-modifying the blog app to add your own custom fields.
+the ``blog`` app, which completely goes against the notion of not
+modifying the ``blog`` app to add your own custom fields.
 
 One approach to address this is to use Django's
 :django:setting:`MIGRATION_MODULES`
@@ -117,6 +117,25 @@ some manual intervention by way of editing migrations, or modifying
 the database manually to create the correct state. Ultimately there is
 a trade-off involved here.
 
+Field Injection Alternatives
+============================
+
+If you don't want to deal with keeping separate migration histories of
+third-party models you can use the "Model Customization" pattern:
+
+#. Create a new model in your own project. Following the previous example on
+   :class:`.BlogPost` let's call it ``BlogPostCustomizations``.
+#. Add all your additional fields to this new model.
+#. Add a :class:`django.db.models.OneToOneField` pointing to
+   :class:`.BlogPost`, with ``related_name="customizations"``.
+#. Now all your customizations will be available on ``BlogPost`` instances as
+   ``blogpost.customizations.*``.
+#. To edit the customizations register your new model as an inline of the
+   parent model in the admin (described below).
+
+The main disadvantage with this approach is that accessing your customizations
+will require an additional query.
+
 Admin Fields
 ============
 

docs/multi-lingual-sites.rst

@@ -21,7 +21,7 @@ In order to enable translation fields for Mezzanine content, you will
 need to install django-modeltranslation and activate the app in your
 ``settings.py``. Once you have `installed django-modeltranslation
 <http://django-modeltranslation.readthedocs.org/en/latest/installation.html>`_,
-you can enable support for it by setting the ``USE_MODELTRANSLATION``
+you can enable support for it by setting the :ref:`USE_MODELTRANSLATION`
 setting to ``True`` in your project's ``settings.py`` module, and
 also defining at least two entries in the :django:setting:`LANGUAGES` setting.
 
@@ -32,14 +32,12 @@ older projects, you can catch up by running
 ``manage.py update_translation_fields``.
 
 .. note::
-    A django-modeltranslation setting that can help managing the
-    transition for content *partially* in several languages is
-    ``MODELTRANSLATION_FALLBACK_LANGUAGES``.  This setting allows you
-    to avoid having empty content when the translation is not provided
-    for a specific language. Please consult `django-modeltranslation's
-    documentation
-    <http://django-modeltranslation.readthedocs.org/en/latest/usage.html#fallback-languages>`_
-    for more detail.
+    A django-modeltranslation setting that can help managing the transition for
+    content *partially* in several languages is
+    `MODELTRANSLATION_FALLBACK_LANGUAGES
+    <http://django-modeltranslation.readthedocs.org/en/latest/usage.html#fallback-languages>`_.
+    This setting allows you to avoid having empty content when the translation
+    is not provided for a specific language.
 
 Translation Fields for Custom Applications
 ==========================================

docs/multi-tenancy.rst

@@ -2,10 +2,11 @@
 Multi-Tenancy
 =============
 
-Mezzanine makes use of Django's ``sites`` app to support multiple sites in a
-single project. This functionality is always "turned on" in Mezzanine: a
-single ``Site`` record always exists, and is referenced when retrieving site
-related data, which most content in Mezzanine falls under.
+Mezzanine makes use of :doc:`Django's sites app <django:ref/contrib/admin/index>` to
+support multiple sites in a single project. This functionality is always
+"turned on" in Mezzanine: a single :class:`Site
+<django.contrib.sites.models.Site>` record always exists, and is referenced
+when retrieving site related data, which most content in Mezzanine falls under.
 
 Where Mezzanine diverges from Django is how the ``Site`` record is retrieved.
 Typically a running instance of a Django project is bound to a single site
@@ -108,7 +109,7 @@ The project's main ``urls.py`` would need the following line active,
 so that "/" is the target URL Mezzanine finds for home page rendering
 (via the ``HomePage`` content type)::
 
-    url(r"^$", "mezzanine.pages.views.page", {"slug": "/"}, name="home"),
+    path("", "mezzanine.pages.views.page", {"slug": "/"}, name="home"),
 
 Mezzanine will look for a page instance at '/' for each theme.
 ``HomePage`` instances would be created via the admin system for each
@@ -128,7 +129,7 @@ during the development process::
 
 Finally, under /admin, these sites will share some resources, such as
 the media library, while there is separation of content stored in the
-database (independent ``HomePage`` instances, independant blog posts,
+database (independent ``HomePage`` instances, independent blog posts,
 an independent page hierarchy, etc.). Furthermore, the content types
 added to, say ``example_theme``, e.g. ``HomePage``, are shared and
 available in the different sites. Such nuances of sharing must be
@@ -143,12 +144,12 @@ are upgrading from a version lower than 4.3 and getting warnings in the
 terminal about ``TemplateForHostMiddleware``, edit your ``settings.py`` to
 switch to the new loader-based approach:
 
- * Remove ``TemplateForHostMiddleware`` from your ``MIDDLEWARE`` setting.
- * Remove ``"APP_DIRS": True`` from your ``TEMPLATES`` setting.
+ * Remove ``TemplateForHostMiddleware`` from your :django:setting:`MIDDLEWARE` setting.
+ * Remove ``"APP_DIRS": True`` from your :django:setting:`TEMPLATES` setting.
  * Add ``mezzanine.template.loaders.host_themes.Loader`` to the list of
    template loaders.
 
-Your ``TEMPLATES`` setting should look like this (notice the ``"loaders"`` key):
+Your :django:setting:`TEMPLATES`` setting should look like this (notice the ``"loaders"`` key):
 
 .. code:: python