Restructure docs per Diátaxis framework

Add intro, reference, and topic sections.

Author: timgraham

README.md

@@ -10,6 +10,9 @@ explore and build. The best way to share this is via our [MongoDB Community Foru
 * [Model Your Data](https://www.mongodb.com/docs/languages/python/django-mongodb/current/model-data/)
 * [Limitations & Future Work](https://www.mongodb.com/docs/languages/python/django-mongodb/current/limitations-upcoming/)
 
+The documentation in the "docs" directory is online at
+https://django-mongodb-backend.readthedocs.io/en/latest/.
+
 ## Install
 
 Use the version of `django-mongodb-backend` that corresponds to your version of

docs/source/conf.py

@@ -16,8 +16,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.append(str((Path(__file__).parent / "_ext").resolve()))
 
-project = "django_mongodb_backend"
-copyright = "2024, The MongoDB Python Team"
+project = "Django MongoDB Backend"
+copyright = "2025, The MongoDB Python Team"
 author = "The MongoDB Python Team"
 release = _version("django_mongodb_backend")
 
@@ -39,12 +39,15 @@
 intersphinx_mapping = {
     "django": (
         "https://docs.djangoproject.com/en/5.1/",
-        "http://docs.djangoproject.com/en/5.1/_objects/",
+        "https://docs.djangoproject.com/en/5.1/_objects/",
     ),
+    "mongodb": ("https://www.mongodb.com/docs/languages/python/django-mongodb/v5.1/", None),
     "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
     "python": ("https://docs.python.org/3/", None),
 }
 
+root_doc = "contents"
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

docs/source/contents.rst

@@ -0,0 +1,23 @@
+=================
+Table of contents
+=================
+
+.. toctree::
+    :hidden:
+
+    index
+
+.. toctree::
+    :maxdepth: 2
+
+    intro/index
+    topics/index
+    ref/index
+    faq
+    internals
+
+Indices
+=======
+
+* :ref:`genindex`
+* :ref:`modindex`

docs/source/faq.rst

@@ -0,0 +1,34 @@
+===
+FAQ
+===
+
+This page contains a list of some frequently asked questions.
+
+Troubleshooting
+===============
+
+Debug logging
+-------------
+
+To troubleshoot MongoDB connectivity issues, you can enable :doc:`PyMongo's
+logging <pymongo:examples/logging>` using :doc:`Django's LOGGING setting
+<django:topics/logging>`.
+
+This is a minimal :setting:`LOGGING` setting that enables PyMongo's ``DEBUG``
+logging::
+
+    LOGGING = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+            },
+        },
+        "loggers": {
+            "pymongo": {
+                "handlers": ["console"],
+                "level": "DEBUG",
+            },
+        },
+    }

docs/source/index.rst

@@ -1,19 +1,48 @@
-django-mongodb-backend 5.1.x documentation
-==========================================
+======================
+Django MongoDB Backend
+======================
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+version 5.1.x for Django 5.1.x
 
-   fields
-   querysets
-   forms
-   models
-   embedded-models
+.. rubric:: Everything you need to know about Django MongoDB Backend.
 
-Indices and tables
-==================
+First steps
+===========
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+**Getting started:**
+
+- :doc:`Installation <intro/install>`
+- :doc:`Configuration <intro/configure>`
+
+Getting help
+============
+
+Having trouble? We’d like to help!
+
+- Try the :doc:`faq` – it’s got answers to many common questions.
+
+- Looking for specific information? Try the :ref:`genindex`, :ref:`modindex`,
+  or the detailed :doc:`table of contents <contents>`.
+
+- Didn't find an answer? You're welcome to ask questions or give feedback on
+  the `MongoDB Community Forum <https://www.mongodb.com/community/forums/tag/python>`_.
+
+- Report bugs and request features in our :ref:`issue tracker <issue-tracker>`.
+
+Models
+======
+
+**Reference material:**
+
+- :doc:`ref/models/fields`
+- :doc:`ref/models/querysets`
+- :doc:`ref/models/models`
+
+**Topic guides:**
+
+- :doc:`topics/embedded-models`
+
+Forms
+=====
+
+- :doc:`ref/forms`

docs/source/internals.rst

@@ -0,0 +1,25 @@
+=================
+Project internals
+=================
+
+Documentation for people working on Django MongoDB Backend itself. This is the
+place to go if you'd like to help improve Django MongoDB Backend or learn about
+how the project is managed.
+
+.. _issue-tracker:
+
+Issue tracker
+=============
+
+To report a bug or to request a new feature in Django MongoDB Backend, please
+open an issue in our issue tracker, JIRA:
+
+1. Create a `JIRA account <https://jira.mongodb.org/>`_.
+
+2. Navigate to the `Python Integrations project
+   <https://jira.mongodb.org/projects/INTPYTHON/>`_.
+
+3. Click **Create Issue**. Please provide as much information as possible about
+   the issue and the steps to reproduce it.
+
+Bug reports in JIRA for this project can be viewed by everyone.

docs/source/intro/configure.rst

@@ -0,0 +1,157 @@
+===================================================
+Configuring a project to use Django MongoDB Backend
+===================================================
+
+Aftering :doc:`installing Django MongoDB Backend <install>`, you must take some
+additional steps to configure your project.
+
+.. _specifying the-default-pk-field:
+
+Specifying the default primary key field
+========================================
+
+In your Django settings, you must specify that all models should use
+:class:`~django_mongodb_backend.fields.ObjectIdAutoField`.
+
+You can create a new project that's configured based on these steps using a
+project template:
+
+.. code-block:: bash
+
+    $ django-admin startproject mysite --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.1.x.zip
+
+(If you're using a version of Django other than 5.1.x, replace the two numbers
+to match the first two numbers from your version.)
+
+This template includes the following line in ``settings.py``::
+
+    DEFAULT_AUTO_FIELD = "django_mongodb_backend.fields.ObjectIdAutoField"
+
+But this setting won't override any apps that have an ``AppConfig`` that
+specifies :attr:`~django.apps.AppConfig.default_auto_field`. For those apps,
+you'll need to create a custom :class:`~django.apps.AppConfig`.
+
+For example, the project template includes ``<project_name>/apps.py``::
+
+    from django.contrib.admin.apps import AdminConfig
+    from django.contrib.auth.apps import AuthConfig
+    from django.contrib.contenttypes.apps import ContentTypesConfig
+
+
+    class MongoAdminConfig(AdminConfig):
+        default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField"
+
+
+    class MongoAuthConfig(AuthConfig):
+        default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField"
+
+
+    class MongoContentTypesConfig(ContentTypesConfig):
+        default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField"
+
+Each app reference in the :setting:`INSTALLED_APPS` setting must point to the
+corresponding ``AppConfig``. For example, instead of ``'django.contrib.admin'``,
+the template uses ``'<project_name>.apps.MongoAdminConfig'``.
+
+Configuring migrations
+======================
+
+Because all models must use
+:class:`~django_mongodb_backend.fields.ObjectIdAutoField`, each third-party
+and contrib app you use needs to have its own migrations specific to MongoDB.
+
+For example, ``settings.py`` in the project template specifies::
+
+    MIGRATION_MODULES = {
+        "admin": "mongo_migrations.admin",
+        "auth": "mongo_migrations.auth",
+        "contenttypes": "mongo_migrations.contenttypes",
+    }
+
+The project template includes these migrations, but you can generate them if
+you're setting things up manually or if you need to create migrations for
+third-party apps. For example:
+
+.. code-block:: bash
+
+    $ python manage.py makemigrations admin auth contenttypes
+    Migrations for 'admin':
+      mongo_migrations/admin/0001_initial.py
+        - Create model LogEntry
+    ...
+
+Creating Django applications
+============================
+
+Whenever you run ``python manage.py startapp``, you must remove the line::
+
+    default_auto_field = 'django.db.models.BigAutoField'
+
+from the new application's ``apps.py`` file (or change it to reference
+``"django_mongodb_backend.fields.ObjectIdAutoField"``).
+
+Alternatively, you can use the following :djadmin:`startapp` template which
+includes this change:
+
+.. code-block:: bash
+
+    $ python manage.py startapp myapp --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.1.x.zip
+
+(If you're using a version of Django other than 5.1.x, replace the two numbers
+to match the first two numbers from your version.)
+
+.. _configuring-databases-setting:
+
+Configuring the ``DATABASES`` setting
+=====================================
+
+After you've set up a project, configure Django's :setting:`DATABASES` setting
+similar to this::
+
+    DATABASES = {
+        "default": {
+            "ENGINE": "django_mongodb_backend",
+            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
+            "NAME": "my_database",
+            "USER": "my_user",
+            "PASSWORD": "my_password",
+            "PORT": 27017,
+            "OPTIONS": {
+                # Example:
+                "retryWrites": "true",
+                "w": "majority",
+                "tls": "false",
+            },
+        },
+    }
+
+For a localhost configuration, you can omit :setting:`HOST` or specify
+``"HOST": "localhost"``.
+
+:setting:`HOST` only needs a scheme prefix for SRV connections
+(``mongodb+srv://``). A ``mongodb://`` prefix is never required.
+
+:setting:`OPTIONS` is an optional dictionary of parameters that will be passed
+to :class:`~pymongo.mongo_client.MongoClient`.
+
+Specify :setting:`USER` and :setting:`PASSWORD` if your database requires
+authentication.
+
+:setting:`PORT` is optional if unchanged from MongoDB's default of 27017.
+
+For a replica set or sharded cluster where you have multiple hosts, include
+all of them in :setting:`HOST`, e.g.
+``"mongodb://mongos0.example.com:27017,mongos1.example.com:27017"``.
+
+Alternatively, if you prefer to simply paste in a MongoDB URI rather than parse
+it into the format above, you can use
+:func:`~django_mongodb_backend.utils.parse_uri`::
+
+    import django_mongodb_backend
+
+    MONGODB_URI = "mongodb+srv://my_user:[email protected]/myDatabase?retryWrites=true&w=majority&tls=false"
+    DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI)
+
+This constructs a :setting:`DATABASES` setting equivalent to the first example.
+
+Congratulations, your project is ready to go!

docs/source/intro/index.rst

@@ -0,0 +1,26 @@
+===============
+Getting started
+===============
+
+New to Django or MongoDB? Well, you came to the right place: read this material
+to quickly get up and running.
+
+.. toctree::
+   :maxdepth: 1
+
+   install
+   configure
+
+.. seealso::
+
+    If you're new to Django_, you might want to start by getting an idea of
+    what it's like.
+
+    For a tutorial that covers using this library with MongoDB Atlas (a fully
+    managed cloud database service that hosts MongoDB), read
+    :doc:`mongodb:get-started`.
+
+    Another excellent tutorial that covers Django in more detail is the
+    :doc:`official Django tutorial <django:intro/tutorial01>`.
+
+    .. _Django: https://www.djangoproject.org/

docs/source/intro/install.rst

@@ -0,0 +1,17 @@
+=================================
+Installing Django MongoDB Backend
+=================================
+
+Use the version of ``django-mongodb-backend`` that corresponds to your version
+of Django. For example, to get the latest compatible release for Django 5.1.x:
+
+.. code-block:: bash
+
+    $ pip install --pre django-mongodb-backend==5.1.*
+
+(Until the package is out of beta, you must use pip's ``--pre`` option.)
+
+The minor release number of Django doesn't correspond to the minor release
+number of ``django-mongodb-backend``. Use the latest minor release of each.
+
+Next, you'll have to :doc:`configure your project <configure>`.