DOCSP-43200: Get started with Django

snooty.toml

@@ -25,12 +25,14 @@ 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 = "Django MongoDB"
 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,28 @@
+.. _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.
+   :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/>

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

@@ -0,0 +1,89 @@
+.. _django-get-started-connect:
+
+=================================
+Configure your MongoDB Connection
+=================================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: app, odm, code example
+
+.. 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
+
+         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",
+               "NAME": "db",
+               "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.
+
+   .. 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/. You should see a "Congratulations!"
+      message and an image of a rocket. 
+

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

@@ -0,0 +1,61 @@
+.. _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:`Database` section and click the :guilabel:`Connect` button
+      for your new deployment.
+
+      .. figure:: /includes/figures/atlas_connection_select_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.
+
+      Select the :guilabel:`Password (SCRAM)` authentication mechanism.
+
+      Deselect the :guilabel:`Include full driver code example` option to view
+      the connection string.
+
+   .. 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-app.txt

@@ -0,0 +1,128 @@
+.. _django-get-started-create-app:
+
+=====================
+Create an Application
+=====================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: app, odm, code example
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create a "sample_mflix" app
+
+      From your ``quickstart`` project directory, run the following command to create a 
+      new Django app called ``sample_mflix`` based on a custom template:
+
+      .. code-block:: bash
+
+         python3 manage.py startapp sample_mflix --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip
+
+      .. note:: App Template
+
+         The ``django-mongodb-app`` template ensures that your ``app.py`` file
+         includes the line ``"default_auto_field = 'django_mongodb.fields.ObjectIdAutoField'"``.
+
+   .. step:: Create a view
+
+      Open the ``views.py`` file in your ``sample_mflix`` directory and replace
+      its contents with the following code:
+
+      .. code-block:: python
+
+         from django.http import HttpResponse
+
+
+         def index(request):
+            return HttpResponse("Hello, world. You're at the application index.")
+
+   .. step:: Configure a URL
+
+      Create a new file called ``urls.py`` file in your ``sample_mflix`` directory and add
+      the following code:
+
+      .. code-block:: python
+
+         from django.urls import path
+
+         from . import views
+
+         urlpatterns = [
+            path("", views.index, name="index"),
+         ]
+
+      Then, navigate to the ``quickstart/urls.py`` file and replace its contents with
+      the following code:
+
+      .. code-block:: python
+
+         from django.contrib import admin
+         from django.urls import include, path
+
+         urlpatterns = [
+            path("sample_mflix/", include("sample_mflix.urls")),
+            path("admin/", admin.site.urls),
+         ]
+
+      Visit http://127.0.0.1:8000/sample_mflix/ to see the text defined in your view.
+
+   .. step:: Apply database migrations
+
+      From your project root, run the following command:
+
+      .. code-block:: bash
+
+         python manage.py migrate
+
+   .. step:: Create models for movie and users data
+
+      Open the ``models.py`` file in the ``sample_mflix`` directory and replace 
+      its contents with the following code:
+
+      .. code-block:: python
+
+         from django.db import models
+
+
+         class Movies(models.Model):
+            name = models.CharField(max_length=200)
+            runtime = models.IntegerField(default=0)
+
+
+         class Users(models.Model):
+            name = models.CharField(max_length=200)
+            email = models.CharField(max_length=200)
+
+
+   .. step:: Include your app in your project
+
+      Open the ``settings.py`` file in ``quickstart`` and edit your 
+      ``INSTALLED_APPS`` setting to resemble the following code:
+
+      .. code-block:: python
+
+         INSTALLED_APPS = [
+            'sample_mflix.apps.SampleMflixConfig',
+            'quickstart.apps.MongoAdminConfig',
+            'quickstart.apps.MongoAuthConfig',
+            'quickstart.apps.MongoContentTypesConfig',
+            'django.contrib.sessions',
+            'django.contrib.messages',
+            'django.contrib.staticfiles',
+         ]
+
+   .. step:: Create migrations for your new models
+
+      From your project root, run the following command to create
+      migrations for the ``Movies`` and ``Users`` models and Apply
+      the changes to the database:
+
+      .. code-block:: bash
+
+         python3 manage.py makemigrations sample_mflix
+         python3 manage.py migrate

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

@@ -0,0 +1,27 @@
+.. _django-get-started-create-deployment:
+
+===========================
+Create a MongoDB Deployment
+===========================
+
+You can create a free tier MongoDB deployment on MongoDB Atlas
+to store and manage your data. MongoDB Atlas hosts and manages
+your MongoDB database in the cloud.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create a Free MongoDB deployment on Atlas
+
+      Complete the :atlas:`Get Started with Atlas </getting-started?tck=docs_driver_python>`
+      guide to set up a new Atlas account and load sample data into a new free
+      tier MongoDB deployment.
+
+   .. step:: Save your Credentials
+
+      After you create your database user, save that user's 
+      username and password to a safe location for use in an upcoming step.
+
+After you complete these steps, you have a new free tier MongoDB
+deployment on Atlas, database user credentials, and sample data loaded
+in your database.