restructure docs per Diátaxis framework

Add intro, reference, and topic sections
timgraham · Jan 28, 2025 · 1eb584b · 1eb584b
1 parent e42e7e3
commit 1eb584b
Show file tree

Hide file tree

Showing 18 changed files with 401 additions and 219 deletions.
diff --git a/README.md b/README.md
@@ -4,177 +4,6 @@ This backend is currently in development and is not advised for Production workf
 changes may be made without notice. We welcome your feedback as we continue to
 explore and build. The best way to share this is via our [MongoDB Community Forum](https://www.mongodb.com/community/forums/tag/python)
 
-## Install and usage
-
-The development version of this package supports Django 5.0.x. To install it:
-
-`pip install git+https://github.com/mongodb-labs/django-mongodb-backend`
-
-### Specifying the default primary key field
-
-In your Django settings, you must specify that all models should use
-`ObjectIdAutoField`.
-
-You can create a new project that's configured based on these steps using a
-project template:
-
-```bash
-$ django-admin startproject mysite --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip
-```
-(where "5.0" matches the version of Django that you're using.)
-
-This template includes the following line in `settings.py`:
-
-```python
-DEFAULT_AUTO_FIELD = "django_mongodb_backend.fields.ObjectIdAutoField"
-```
-
-But this setting won't override any apps that have an `AppConfig` that
-specifies `default_auto_field`. For those apps, you'll need to create a custom
-`AppConfig`.
-
-For example, the project template includes `<project_name>/apps.py`:
-
-```python
-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 `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 `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:
-
-```python
-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:
-
-```console
-$ 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 `startapp` template which includes
-this change:
-
-```bash
-$ python manage.py startapp myapp --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip
-```
-(where "5.0" matches the version of Django that you're using.)
-
-### Configuring the `DATABASES` setting
-
-After you've set up a project, configure Django's `DATABASES` setting similar
-to this:
-
-```python
-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 `HOST` or specify
-`"HOST": "localhost"`.
-
-`HOST` only needs a scheme prefix for SRV connections (`mongodb+srv://`). A
-`mongodb://` prefix is never required.
-
-`OPTIONS` is an optional dictionary of parameters that will be passed to
-[`MongoClient`](https://pymongo.readthedocs.io/en/stable/api/pymongo/mongo_client.html).
-
-`USER`, `PASSWORD`, and `PORT` (if 27017) may also be optional.
-
-For a replica set or sharded cluster where you have multiple hosts, include
-all of them in `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:
-
-```python
-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 `DATABASES` setting equivalent to the first example.
-
-#### `django_mongodb_backend.parse_uri(uri, conn_max_age=0, test=None)`
-
-`parse_uri()` provides a few options to customize the resulting `DATABASES`
-setting, but for maximum flexibility, construct `DATABASES` manually as
-described above.
-
-- Use `conn_max_age` to configure [persistent database connections](
-  https://docs.djangoproject.com/en/stable/ref/databases/#persistent-database-connections).
-- Use `test` to provide a dictionary of [settings for test databases](
-  https://docs.djangoproject.com/en/stable/ref/settings/#test).
-
-Congratulations, your project is ready to go!
-
-## Notes on Django QuerySets
-
-* `QuerySet.explain()` supports the [`comment` and `verbosity` options](
-  https://www.mongodb.com/docs/manual/reference/command/explain/#command-fields).
-
-   Example: `QuerySet.explain(comment="...", verbosity="...")`
-
-   Valid values for `verbosity` are `"queryPlanner"` (default),
-   `"executionStats"`, and `"allPlansExecution"`.
-
 ## Known issues and limitations
 
 - The following `QuerySet` methods aren't supported:
@@ -220,31 +49,3 @@ Congratulations, your project is ready to go!
 
 - Due to the lack of ability to introspect MongoDB collection schema,
   `migrate --fake-initial` isn't supported.
-
-## Troubleshooting
-
-### Debug logging
-
-To troubleshoot MongoDB connectivity issues, you can enable [PyMongo's logging](
-https://pymongo.readthedocs.io/en/stable/examples/logging.html) using
-[Django's `LOGGING` setting](https://docs.djangoproject.com/en/stable/topics/logging/).
-
-This is a minimal `LOGGING` setting that enables PyMongo's `DEBUG` logging:
-
-```python
-LOGGING = {
-    "version": 1,
-    "disable_existing_loggers": False,
-    "handlers": {
-        "console": {
-            "class": "logging.StreamHandler",
-        },
-    },
-    "loggers": {
-        "pymongo": {
-            "handlers": ["console"],
-            "level": "DEBUG",
-        },
-    },
-}
-```
diff --git a/docs/source/conf.py b/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")
 
@@ -45,6 +45,8 @@
     "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
 

diff --git a/docs/source/contents.rst b/docs/source/contents.rst
@@ -0,0 +1,23 @@
+=================
+Table of contents
+=================
+
+.. toctree::
+    :hidden:
+
+    index
+
+.. toctree::
+    :maxdepth: 2
+
+    intro/index
+    topics/index
+    faq
+    ref/index
+    internals
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
diff --git a/docs/source/faq.rst b/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",
+            },
+        },
+    }
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,19 +1,45 @@
-django-mongodb-backend 5.0.x documentation
-==========================================
+======================
+Django MongoDB Backend
+======================
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+version 5.0.x for Django 5.0.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>`.
+
+- 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`
diff --git a/docs/source/internals.rst b/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.