DOCSP-43200: Get started with Django

snooty.toml

@@ -12,6 +12,7 @@ toc_landing_pages = [
     "/security",
     "/aggregation-tutorials",
     "/data-formats",
+    "/django-get-started",
 ]
 
 intersphinx = [
@@ -25,12 +26,15 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 driver-short = "PyMongo"
 driver-long = "PyMongo, the MongoDB synchronous Python driver,"
 driver-async = "PyMongo Async"
+django-odm = "MongoDB Backend for Django"
+django-api = "https://django-mongodb.readthedocs.io/en/latest/"
 language = "Python"
 mdb-server = "MongoDB Server"
 mongo-community = "MongoDB Community Edition"
 mongo-enterprise = "MongoDB Enterprise Edition"
 docs-branch = "master"                                                       # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
 version-number = "4.10"
+django-version-number = "5.0"
 patch-version-number = "{+version-number+}.1"                                # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
 version = "v{+version-number+}"
 stable-api = "Stable API"

source/django-get-started.txt

@@ -0,0 +1,45 @@
+.. _django-get-started:
+
+===============================
+Get Started with {+django-odm+}
+===============================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :description: Learn how to create an app to connect to a MongoDB deployment by using Django MongoDB Backend.
+   :keywords: quick start, tutorial, basics
+
+.. toctree::
+
+   Download & Install </django-get-started/django-install/>
+   Create a Deployment </django-get-started/django-create-deployment/>
+   Create a Connection String </django-get-started/django-connection-string/>
+   Configure a MongoDB Connection </django-get-started/django-connect-mongodb/>
+   Create an Application </django-get-started/django-create-app/>
+   Write Data to MongoDB </django-get-started/django-write-data/>
+   Query MongoDB Data </django-get-started/django-query-data/>
+   Create an Admin Site </django-get-started/django-create-admin/>
+   Next Steps </django-get-started/django-next-steps/>
+
+{+django-odm+} is a PyMongo integration that allows you to use the
+MongoDB document model in your Django application. This tutorial shows
+you how to create a Django app, connect to MongoDB cluster hosted on
+MongoDB Atlas, and interact with data in your cluster.
+
+.. tip:: 
+
+   MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB
+   deployments. You can create your own free (no credit card required) MongoDB Atlas 
+   deployment by following the steps in this guide.
+
+Follow this tutorial to connect a sample Django application to a MongoDB Atlas
+deployment. 

source/django-get-started/django-connect-mongodb.txt

@@ -0,0 +1,96 @@
+.. _django-get-started-connect:
+
+=================================
+Configure your MongoDB Connection
+=================================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: app, odm, code example
+
+After installing {+django-odm+} and creating a MongoDB Atlas deployment,
+you can create a Django project that connects to MongoDB.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create a Django project
+
+      From your shell, run the following command to create a 
+      new Django project called ``quickstart`` based on a custom template:
+
+      .. code-block:: bash
+
+         django-admin startproject quickstart --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/{+django-version-number+}.x.zip
+
+      .. note:: Project Template
+
+         The ``django-mongodb-project`` template resembles the default Django project
+         template but makes the following changes:
+
+         - Includes MongoDB-specific migrations
+         - Modifies the ``settings.py`` file to instruct Django
+           to use an ``ObjectId`` value as each model's primary key
+
+      After running this command, your ``quickstart`` project has
+      the following file structure:
+
+      .. code-block:: bash
+         :copyable: false
+
+         quickstart/
+            manage.py
+            mongo_migrations/
+                __init__.py
+                contenttypes/
+                auth/
+                admin/
+            quickstart/
+                __init__.py
+                apps.py
+                settings.py
+                urls.py
+                asgi.py
+                wsgi.py
+
+   .. step:: Update your database settings
+
+      Open your ``settings.py`` file and navigate to the ``DATABASES`` setting.
+      Replace this setting with the following code:
+
+      .. code-block:: bash
+
+         DATABASES = {
+            "default": {
+               "ENGINE": "django_mongodb_backend",
+               "NAME": "sample_mflix",
+               "USER": "<username>",
+               "PASSWORD": "<password>",
+               "HOST": "<connection string URI>",
+            },
+         }
+
+      Replace the ``<username>`` and ``<password>`` placeholders with your
+      Atlas database user's username and password. Then, replace the
+      ``<connection string URI>`` placeholder with the connection string
+      that you copied from the :ref:`django-get-started-connection-string`
+      step of this guide. This configures your Django app to connect to
+      your Atlas deployment and access the ``sample_mflix`` sample database.
+
+   .. step:: Start the server
+
+      To verify that you installed {+django-odm+} and correctly configured
+      your project, run the following command from your project root:
+
+      .. code-block:: bash
+
+         python3 manage.py runserver
+
+      Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!"
+      message and an image of a rocket. 
+
+After completing these steps, you have a Django project configured
+to use MongoDB.

source/django-get-started/django-connection-string.txt

@@ -0,0 +1,56 @@
+.. _django-get-started-connection-string:
+
+==========================
+Create a Connection String
+==========================
+
+You can connect to your MongoDB deployment by providing a
+**connection URI**, also called a *connection string*, which
+instructs the driver on how to connect to a MongoDB deployment
+and how to behave while connected.
+
+The connection string includes the hostname or IP address and 
+port of your deployment, the authentication mechanism, user credentials 
+when applicable, and connection options.
+
+To connect to an instance or deployment not hosted on Atlas, see
+:ref:`pymongo-connection-targets` in the PyMongo documentation.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Find your MongoDB Atlas connection string
+
+      To retrieve your connection string for the deployment that
+      you created in the :ref:`previous step <django-get-started-create-deployment>`,
+      log into your Atlas account and navigate to the
+      :guilabel:`Clusters` section and click the :guilabel:`Connect` button
+      for your new deployment.
+
+      .. figure:: /includes/figures/atlas_connection_connect_cluster.png
+         :alt: The connect button in the clusters section of the Atlas UI
+
+      Proceed to the :guilabel:`Connect your application` section and select
+      "Python" from the :guilabel:`Driver` selection menu and the version
+      that best matches the version you installed from the :guilabel:`Version`
+      selection menu.
+
+   .. step:: Copy your connection string
+
+      Click the button on the right of the connection string to copy it to
+      your clipboard as shown in the following screenshot:
+
+      .. figure:: /includes/figures/atlas_connection_copy_string_python.png
+         :alt: The connection string copy button in the Atlas UI
+
+   .. step:: Update the placeholders
+
+      Paste this connection string into a file in your preferred text editor
+      and replace the ``<username>`` and ``<password>`` placeholders with
+      your database user's username and password.
+
+      Save this file to a safe location for use in the next step.
+
+After completing these steps, you have a connection string that
+contains your database username and password.
+

source/django-get-started/django-create-admin.txt

@@ -0,0 +1,129 @@
+.. _django-get-started-create-admin:
+
+====================
+Create an Admin Site
+====================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: app, odm, code example
+
+You can create a Django admin site to edit your application's 
+data from a web interface. To learn more about the Django admin
+site and its features, see `The Django admin site <https://docs.djangoproject.com/en/5.1/ref/contrib/admin/>`__
+in the Django documentation.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create an admin user
+
+      Before creating an admin site, you must create a user
+      who can log in to the site. 
+
+      From your project's root directory, run the following command to create
+      an admin user:
+
+      .. code-block:: bash
+
+         python3 manage.py createsuperuser
+
+      Then, your terminal prompts you for a username, email address,
+      and password. For each prompt, enter the following information
+      to create a user with the specified credentials and press "enter"
+      after each entry:
+
+      .. code-block:: bash
+
+         Username: admin
+         Email address: [email protected]
+         Password: <admin-password>
+         Password (again): <admin-password>
+
+      Replace the ``<admin-password>`` placeholder with your user's password.
+
+   .. step:: Enter the admin site
+
+      Run the following code to start your server:
+
+      .. code-block:: bash
+
+         python3 manage.py runserver
+
+      Once your server is running, visit the http://127.0.0.1:8000/admin/ 
+      URL to see the admin site. This site displays the following login
+      screen:
+
+      .. figure:: /includes/figures/django_admin_login.png
+         :alt: The login screen on the Django admin page.
+
+      Enter the username and password created in the previous step to log in to
+      the site. 
+
+   .. step:: Access your "sample_mflix" app from the admin site
+
+      After logging in to the admin site, you can see the following information:
+
+      .. figure:: /includes/figures/django_admin_index.png
+         :alt: The initial content displayed on the Django admin site.
+
+      You can edit your project's authentication configuration by selecting
+      the :guilabel:`Groups` or :guilabel:`Users` row in the 
+      :guilabel:`Authentication and Authorization` table.
+
+      To edit the data in the ``users`` sample collection, represented by your
+      ``Viewer`` model, navigate to your project's ``sample_mflix/admin.py`` file
+      and paste the following code:
+
+      .. code-block:: python
+
+         from django.contrib import admin
+
+         from .models import Viewer
+
+         admin.site.register(Viewer)
+
+      Now, your admin site displays the following information:
+
+      .. figure:: /includes/figures/django_admin_model.png
+         :alt: The content displayed on the Django admin site after registering a model.
+
+   .. step:: Select a Viewer object
+
+      You can view the data stored in a ``Viewer`` object that
+      has a ``name`` value of ``"Abigail Carter"``. You created
+      this object in the :ref:`django-get-started-write` step
+      of this tutorial.
+
+      Click on the :guilabel:`Viewers` row of the :guilabel:`SAMPLE_MFLIX`
+      table to see a list of viewers. The admin site displays the following
+      list:
+
+      .. figure:: /includes/figures/django_admin_viewers.png
+         :alt: The list of viewers displayed on the admin site.
+
+      Then, click on :guilabel:`Abigail Carter` at the top of the list.
+      The site displays the :guilabel:`Name`, :guilabel:`Email`, and :guilabel:`Password`
+      of the selected viewer:
+
+      .. figure:: /includes/figures/django_admin_edit_viewer.png
+         :alt: The information of your selected viewer.
+
+   .. step:: Edit the data in a Viewer object
+
+      To edit the ``email`` field of the viewer, select the 
+      box that contains the text ``"[email protected]"``.
+      Delete this text and replace it with ``"[email protected]"``,
+      as shown in the following image:
+
+      .. figure:: /includes/figures/django_admin_new_email.png
+         :alt: The updated email address of your viewer.
+
+      Then, click the :guilabel:`SAVE` button below the viewer's 
+      information to save your changes.
+
+After completing these steps, you can access the Django
+admin site and use it to edit your ``Viewer`` objects.