DOCSP-37009 - Quick Start page (#1)

mongoKart · web-flow · commit a46a956bb85b · 2024-02-20T13:12:50.000-06:00
diff --git a/source/quick-start.txt b/source/quick-start.txt
@@ -11,215 +11,235 @@ Quick Start
    :depth: 2
    :class: singlecol
 
+.. facet::
+   :name: genre
+   :values: tutorial
+ 
+.. meta::
+   :keywords: pypi, pip, xcode
+
 This tutorial is intended as an introduction to working with
 **MongoDB** and **PyMongo**.
 
 Download and Install
 --------------------
 
-**PyMongo** is in the `Python Package Index
-<http://pypi.python.org/pypi/pymongo/>`_.
+**PyMongo** is in the `Python Package Index.
+<http://pypi.python.org/pypi/pymongo/>`__
 
-.. warning:: **Do not install the "bson" package from pypi.** PyMongo comes
-   with its own bson package; doing "pip install bson" or "easy_install bson"
+.. warning::
+  
+   Do not install the ``bson`` package from PyPI. PyMongo comes
+   with its own ``bson`` package. Running ``pip install bson`` or ``easy_install bson``
    installs a third-party package that is incompatible with PyMongo.
 
 Installing with pip
 -------------------
 
-We recommend using `pip <http://pypi.python.org/pypi/pip>`_
-to install pymongo on all platforms:
+We recommend using `pip <http://pypi.python.org/pypi/pip>`__
+to install PyMongo on all platforms:
 
 .. code-block:: python
 
-  $ python3 -m pip install pymongo
+   $ python3 -m pip install pymongo
 
-To get a specific version of pymongo:
+To get a specific version of PyMongo:
 
 .. code-block:: python
 
-  $ python3 -m pip install pymongo==3.5.1
+   $ python3 -m pip install pymongo==3.5.1
 
-To upgrade using pip:
+To upgrade by using pip:
 
 .. code-block:: python
 
-  $ python3 -m pip install --upgrade pymongo
+   $ python3 -m pip install --upgrade pymongo
 
 Dependencies
 ------------
 
 PyMongo supports CPython 3.7+ and PyPy3.7+.
 
-Required dependencies
-.....................
-
-Support for mongodb+srv:// URIs requires `dnspython
-<https://pypi.python.org/pypi/dnspython>`_
+Support for mongodb+srv:// URIs requires `dnspython.
+<https://pypi.python.org/pypi/dnspython>`__
 
-Installing from source
+Installing from Source
 ----------------------
 
-If you'd rather install directly from the source (i.e. to stay on the
-bleeding edge), install the C extension dependencies then check out the
+If you'd rather install PyMongo directly from the source,
+install the C-extension dependencies, and then check out the
 latest source from GitHub and install the driver from the resulting tree:
 
 .. code-block:: python
 
-  $ git clone https://github.com/mongodb/mongo-python-driver.git pymongo
-  $ cd pymongo/
-  $ pip install .
+   $ git clone https://github.com/mongodb/mongo-python-driver.git pymongo
+   $ cd pymongo/
+   $ pip install .
 
-Installing from source on Unix
-..............................
+Installing from Source on Unix
+``````````````````````````````
 
-To build the optional C extensions on Linux or another non-macOS Unix you must
-have the GNU C compiler (gcc) installed. Depending on your flavor of Unix
-(or Linux distribution) you may also need a python development package that
+To build the optional C extensions on Linux or another non-macOS Unix, you must
+have the GNU C compiler (``gcc``) installed. Depending on your flavor of Unix
+(or Linux distribution), you may also need a Python development package that
 provides the necessary header files for your version of Python. The package
-name may vary from distro to distro.
+name might vary among distrubutions.
 
-Debian and Ubuntu users should issue the following command:
+If you're using Debian or Ubuntu, run the following command:
 
 .. code-block:: python
 
-  $ sudo apt-get install build-essential python-dev
-
-Users of Red Hat based distributions (RHEL, CentOS, Amazon Linux, Oracle Linux,
-Fedora, etc.) should issue the following command:
-
-.. code-block:: python
-
-  $ sudo yum install gcc python-devel
-
-Installing from source on macOS / OSX
-.....................................
+   $ sudo apt-get install build-essential python-dev
 
-If you want to install PyMongo with C extensions from source you will need
-the command line developer tools. On modern versions of macOS they can be
-installed by running the following in Terminal (found in
-/Applications/Utilities/):
+If you're using a Red Hat-based distribution (RHEL, CentOS, Amazon Linux, Oracle Linux,
+Fedora, etc.), run the following command:
 
 .. code-block:: python
 
-  xcode-select --install
+   $ sudo yum install gcc python-devel
 
-For older versions of OSX you may need Xcode. See the notes below for various
-OSX and Xcode versions.
+Installing from Source on macOS or OSX
+``````````````````````````````````````
 
-**Snow Leopard (10.6)** - Xcode 3 with 'UNIX Development Support'.
+If you want to install PyMongo with C extensions from source, you will need
+the command line developer tools. On modern versions of macOS, you can
+install these tools by running the following command in your terminal:
 
-**Snow Leopard Xcode 4**: The Python versions shipped with OSX 10.6.x
-are universal binaries. They support i386, PPC, and x86_64. Xcode 4 removed
-support for PPC, causing the distutils version shipped with Apple's builds of
-Python to fail to build the C extensions if you have Xcode 4 installed. There
-is a workaround:
+.. code-block:: bash
 
-.. code-block:: python
+   xcode-select --install
 
-  # For some Python builds from python.org
-  $ env ARCHFLAGS='-arch i386 -arch x86_64' python -m easy_install pymongo
+The following list describes the installation requirements for older versions of OSX:
 
-See `http://bugs.python.org/issue11623 <http://bugs.python.org/issue11623>`_
-for a more detailed explanation.
+- **Lion (10.7) and newer**: PyMongo's C extensions can be built against
+  versions of Python 3.7+ downloaded from python.org. In all cases, you must install Xcode
+  with "UNIX Development Support". 
+  
+  Starting with Xcode version 5.1, ``clang``
+  throws an error when it encounters compiler flags that it doesn't recognize.
+  This may cause C extension builds to fail with an error similar to the following:
 
-**Lion (10.7) and newer** - PyMongo's C extensions can be built against
-versions of Python 3.7+ downloaded from python.org. In all cases Xcode must be
-installed with 'UNIX Development Support'.
+  .. code-block:: bash
 
-**Xcode 5.1**: Starting with version 5.1 the version of clang that ships with
-Xcode throws an error when it encounters compiler flags it doesn't recognize.
-This may cause C extension builds to fail with an error similar to:
+     clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]
 
-.. code-block:: python
+  You can run one of the following commands as a workaround:
 
-  clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]
+  .. code-block:: python
 
-There are workarounds:
+     # Apple specified workaround for Xcode 5.1
+     # easy_install
+     $ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future easy_install pymongo
+     # or pip
+     $ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install pymongo
 
-.. code-block:: python
+     # Alternative workaround using CFLAGS
+     # easy_install
+     $ CFLAGS=-Qunused-arguments easy_install pymongo
+     # or pip
+     $ CFLAGS=-Qunused-arguments pip install pymongo
 
-  # Apple specified workaround for Xcode 5.1
-  # easy_install
-  $ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future easy_install pymongo
-  # or pip
-  $ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install pymongo
+- **Snow Leopard (10.6)**: Xcode 3 with "UNIX Development Support".
 
-  # Alternative workaround using CFLAGS
-  # easy_install
-  $ CFLAGS=-Qunused-arguments easy_install pymongo
-  # or pip
-  $ CFLAGS=-Qunused-arguments pip install pymongo
+  The Python versions that shipped with OSX 10.6.x
+  are universal binaries. They support i386, PPC, and x86_64 architectures. Xcode 4 removed
+  support for PPC, causing the ``distutils`` version shipped with Apple's builds of
+  Python to fail to build the C extensions if you have Xcode 4 installed. There
+  is a workaround:
 
+  .. code-block:: python
 
-Installing from source on Windows
-.................................
+     # For some Python builds from python.org
+     $ env ARCHFLAGS='-arch i386 -arch x86_64' python -m easy_install pymongo
 
-If you want to install PyMongo with C extensions from source the following
-requirements apply to both CPython and ActiveState's ActivePython:
+  See `http://bugs.python.org/issue11623 <http://bugs.python.org/issue11623>`__
+  for a more detailed explanation.
 
-Windows
-~~~~~~~
+Installing from Source on Windows
+`````````````````````````````````
 
-Install Visual Studio 2015+.
+If you want to install PyMongo with C extensions from source,
+CPython and ActiveState's ActivePython require Visual Studio 2015 or later.
 
 .. _install-no-c:
 
 Installing Without C Extensions
 -------------------------------
 
-By default, the driver attempts to build and install optional C
+By default, PyMongo attempts to build and install optional C
 extensions (used for increasing performance) when it is installed. If
-any extension fails to build the driver will be installed anyway but a
+any extension fails to build, the driver will still be installed, but a
 warning will be printed.
 
-If you wish to install PyMongo without the C extensions, even if the
-extensions build properly, it can be done using a command line option to
-*pip install*:
+If you wish to install PyMongo without the C extensions, run the following command:
 
 .. code-block:: python
 
-  $ NO_EXT=1 python -m pip install .
+   $ NO_EXT=1 python -m pip install .
+
+Installing a Beta or Release-Candidate Version
+----------------------------------------------
 
-Installing a beta or release candidate
---------------------------------------
+MongoDB will occasionally tag a beta or release-candidate version for testing by
+the community before final release. These releases will not be uploaded to PyPI, but you
+can find them on the `GitHub tags page <https://github.com/mongodb/mongo-python-driver/tags>`__
+for PyMongo.
 
-MongoDB, Inc. may occasionally tag a beta or release candidate for testing by
-the community before final release. These releases will not be uploaded to pypi
-but can be found on the
-`GitHub tags page <https://github.com/mongodb/mongo-python-driver/tags>`_.
-They can be installed by passing the full URL for the tag to pip:
+To install one of these versions, pass the full URL for the version as an argument pip,
+as follows:
 
 .. code-block:: python
 
-  $ python3 -m pip install https://github.com/mongodb/mongo-python-driver/archive/4.4.0b0.tar.gz
+   $ python3 -m pip install https://github.com/mongodb/mongo-python-driver/archive/4.4.0b0.tar.gz
 
 Test Your PyMongo Installation
 ------------------------------
 
-In the Python shell, the following should run without raising an exception:
+In the Python shell, the following command should run without raising an exception:
 
 .. code-block:: python
 
-  >>> import pymongo
+   >>> import pymongo
 
 Create a Deployment
 -------------------
 
-This tutorial assumes that a MongoDB instance is running on the
-default host and port. Assuming you have `downloaded and installed
-<https://www.mongodb.com/docs/manual/installation/>`_ MongoDB, you
-can start it like so:
+Follow the `Install MongoDB
+<https://www.mongodb.com/docs/manual/installation/>`__ guide to install MongoDB locally.
+
+Create a Python Application
+---------------------------
+
+In your shell, run the following command to create a directory for your application:
 
 .. code-block:: bash
 
-  $ mongod
+   mkdir python_quickstart
 
-To test your code:
+Run the following command to navigate into the project directory:
 
-  .. code-block:: python
+.. code-block:: bash
+
+   cd python_quickstart
+
+Create a file named ``quickstart.py`` to contain your application, and then copy
+the following code into ``quickstart.py``:
+
+.. code-block:: python
+
+   from pymongo import MongoClient
+
+   client = MongoClient()
+   client.drop_database("test-database")
+
+In the terminal, run the following command to start your application:
+
+.. code-block:: bash
+
+   python3 quickstart.py
 
-  from pymongo import MongoClient
+.. note::
 
-  client = MongoClient()
-  client.drop_database("test-database")
+   This application has no output, but should return you to the command prompt if
+   successful.
+   
