PYTHON-1477 PYTHON-1478 PYTHON-1480 - Doc improvements

behackett · behackett · commit 2c932dfe7717 · 2018-02-22T17:14:28.000-08:00
diff --git a/README.rst b/README.rst
@@ -81,9 +81,9 @@ You can also download the project source and do::
 
   $ python setup.py install
 
-Do **not** install the "bson" package. PyMongo comes with its own bson package;
-doing "easy_install bson" installs a third-party package that is incompatible
-with PyMongo.
+Do **not** install the "bson" package from pypi. PyMongo comes with its own
+bson package; doing "easy_install bson" installs a third-party package that
+is incompatible with PyMongo.
 
 Dependencies
 ============
@@ -123,10 +123,10 @@ Other optional packages:
 - `backports.pbkdf2 <https://pypi.python.org/pypi/backports.pbkdf2/>`_,
   improves authentication performance with SCRAM-SHA-1, the default
   authentication mechanism for MongoDB 3.0+. It especially improves
-  performance on Python older than 2.7.8, or on Python 3 before Python 3.4.
+  performance on Python versions older than 2.7.8.
 - `monotonic <https://pypi.python.org/pypi/monotonic>`_ adds support for
   a monotonic clock, which improves reliability in environments
-  where clock adjustments are frequent. Not needed in Python 3.3+.
+  where clock adjustments are frequent. Not needed in Python 3.
 
 
 Additional dependencies are:
diff --git a/RELEASE.rst b/RELEASE.rst
@@ -5,43 +5,43 @@ Versioning
 ----------
 
 We shoot for a release every few months - that will generally just
-increment the middle version number (e.g. 2.6.3 -> 2.7).
+increment the middle / minor version number (e.g. 3.5.0 -> 3.6.0).
 
-Minor releases are reserved for bug fixes (in general no new features
+Patch releases are reserved for bug fixes (in general no new features
 or deprecations) - they only happen in cases where there is a critical
 bug in a recently released version, or when a release has no new
 features or API changes.
 
 In between releases we add .devN to the version number to denote the version
-under development. So if we just released 3.0, then the current dev
-version would be 3.1.dev0. When we make the next release we
-replace all instances of 3.1.devN in the docs with the new version number.
+under development. So if we just released 3.6.0, then the current dev
+version might be 3.6.1.dev0 or 3.7.0.dev0. When we make the next release we
+replace all instances of 3.x.x.devN in the docs with the new version number.
+
+https://semver.org/
+https://www.python.org/dev/peps/pep-0440/
 
 Deprecation
 -----------
 
 Changes should be backwards compatible unless absolutely necessary. When making
 API changes the approach is generally to add a deprecation warning but keeping
-the existing API functional. Eventually (after at least ~4 releases) we can
-remove the old API.
+the existing API functional. Deprecated features can be removed in a release
+that changes the major version number.
 
 Doing a Release
 ---------------
 
-1. Test release on Python 2.6-2.7 and 3.2-3.4 on Windows, Linux and OSX,
-   with and without the C extension. Generally enough to just run the tests on
-   2.6, 2.7, 3.2 and the latest 3.x version with and without the extension on
-   a single platform, and then just test any version on the other platforms
-   as a sanity check. `python setup.py test` will build the extension
-   and test.  `python tools/clean.py` will remove the extension, and
-   then `python setup.py --no_ext test` will run the tests without
-   it. Run the replica set and mongos high-availability tests with
-   `PYTHONPATH=. python test/high_availability/test_ha.py`. Can also
-   run the doctests: `python setup.py doc -t`. For building extensions
-   on Windows check section below.
+1. Test releases on Python 2.6-2.7 and 3.4+ on Windows, Linux and OSX,
+   with and without the C extensions. It's generally enough to just run the
+   tests on 2.6, 2.7, 3.4 and the latest 3.x version with and without the
+   extensions on a single platform, and then just test any version on the
+   other platforms as a sanity check. `python setup.py test` will build the
+   extensions and test. `python tools/clean.py` will remove the extensions,
+   and then `python setup.py --no_ext test` will run the tests without
+   them. You can also run the doctests: `python setup.py doc -t`.
 
 2. Add release notes to doc/changelog.rst. Generally just summarize/clarify
-   the git log, but might add some more long form notes for big changes.
+   the git log, but you might add some more long form notes for big changes.
 
 3. Search and replace the "devN" version number w/ the new version number (see
    note above).
@@ -58,8 +58,8 @@ Doing a Release
 
 9. Push binaries to PyPI; for each version of python and platform do:`python
    setup.py bdist_egg upload`. Probably best to do `python setup.py bdist_egg`
-   first, to make sure the egg builds properly. On Windows we also push a binary
-   installer. The setup.py target for that is `bdist_wininst`.
+   first, to make sure the egg builds properly. We also publish wheels.
+   `python setup.py bdist_wheel upload`.
 
 10. Make sure to push a build of the new docs (see the apidocs repo).
 
diff --git a/doc/examples/authentication.rst b/doc/examples/authentication.rst
@@ -46,8 +46,7 @@ Or through the MongoDB URI::
   >>> uri = "mongodb://user:password@example.com/the_database?authMechanism=SCRAM-SHA-1"
   >>> client = MongoClient(uri)
 
-For best performance install `backports.pbkdf2`_, especially on Python older
-than 2.7.8, or on Python 3 before Python 3.4.
+For best performance on Python versions older than 2.7.8 install `backports.pbkdf2`_.
 
 .. _backports.pbkdf2: https://pypi.python.org/pypi/backports.pbkdf2/
 
diff --git a/doc/examples/tls.rst b/doc/examples/tls.rst
@@ -30,8 +30,7 @@ When using CPython < 2.7.9 or PyPy < 2.5.1:
 
 Python 3.x
 ``````````
-On Windows, the `wincertstore`_ module is required when using CPython < 3.4.0
-or any version of PyPy3.
+On Windows, the `wincertstore`_ module is required when using PyPy3 < 3.5.
 
 .. _ipaddress: https://pypi.python.org/pypi/ipaddress
 .. _wincertstore: https://pypi.python.org/pypi/wincertstore
diff --git a/doc/installation.rst b/doc/installation.rst
@@ -5,9 +5,9 @@ Installing / Upgrading
 **PyMongo** is in the `Python Package Index
 <http://pypi.python.org/pypi/pymongo/>`_.
 
-.. warning:: **Do not install the "bson" package.** PyMongo comes with its own
-   bson package; doing "pip install bson" or "easy_install bson" installs a
-   third-party package that is incompatible with 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"
+   installs a third-party package that is incompatible with PyMongo.
 
 Installing with pip
 -------------------
@@ -19,7 +19,7 @@ to install pymongo on all platforms::
 
 To get a specific version of pymongo::
 
-  $ python -m pip install pymongo==3.1.1
+  $ python -m pip install pymongo==3.5.1
 
 To upgrade using pip::
 
@@ -80,21 +80,31 @@ Other optional packages:
 - `backports.pbkdf2 <https://pypi.python.org/pypi/backports.pbkdf2/>`_,
   improves authentication performance with SCRAM-SHA-1, the default
   authentication mechanism for MongoDB 3.0+. It especially improves
-  performance on Python older than 2.7.8, or on Python 3 before Python 3.4.
+  performance on Python versions older than 2.7.8.
 - `monotonic <https://pypi.python.org/pypi/monotonic>`_ adds support for
   a monotonic clock, which improves reliability in environments
-  where clock adjustments are frequent. Not needed in Python 3.3+.
+  where clock adjustments are frequent. Not needed in Python 3.
 
 
-Dependencies for installing C Extensions on Unix
-------------------------------------------------
+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
+latest source from github and install the driver from the resulting tree::
+
+  $ git clone git://github.com/mongodb/mongo-python-driver.git pymongo
+  $ cd pymongo/
+  $ python setup.py install
+
+Installing from source on Unix
+..............................
 
-MongoDB, Inc. does not provide statically linked binary packages for Unix
-flavors other than OSX. To build the optional C extensions 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.
+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.
 
 Debian and Ubuntu users should issue the following command::
 
@@ -105,22 +115,18 @@ Fedora, etc.) should issue the following command::
 
   $ sudo yum install gcc python-devel
 
-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
-latest source from github and install the driver from the resulting tree::
+Installing from source on macOS / OSX
+.....................................
 
-  $ git clone git://github.com/mongodb/mongo-python-driver.git pymongo
-  $ cd pymongo/
-  $ python setup.py install
+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/)::
 
-Installing from source on OSX
-.............................
+  xcode-select --install
 
-If you want to install PyMongo from source on OSX you will have to install the
-following to build the C extensions:
+For older versions of OSX you may need Xcode. See the notes below for various
+OSX and Xcode versions.
 
 **Snow Leopard (10.6)** - Xcode 3 with 'UNIX Development Support'.
 
@@ -173,11 +179,10 @@ requirements apply to both CPython and ActiveState's ActivePython:
 ~~~~~~~~~~~~~~
 
 For Python 3.5 and newer install Visual Studio 2015. For Python 3.4
-install Visual Studio 2010. For Python 2.6 and 2.7 install Visual Studio
-2008, or the Microsoft Visual C++ Compiler for Python 2.7. You must use the
-full version of Visual Studio 2010 or 2008 as Visual C++ Express does not
-provide 64-bit compilers. Make sure that you check the "x64 Compilers and
-Tools" option under Visual C++.
+install Visual Studio 2010. You must use the full version of Visual Studio
+2010 as Visual C++ Express does not provide 64-bit compilers. Make sure that
+you check the "x64 Compilers and Tools" option under Visual C++. For Python 2.6
+and 2.7 install the `Microsoft Visual C++ Compiler for Python 2.7`_.
 
 32-bit Windows
 ~~~~~~~~~~~~~~
@@ -186,7 +191,9 @@ For Python 3.5 and newer install Visual Studio 2015.
 
 For Python 3.4 install Visual C++ 2010 Express.
 
-For Python 2.6 and 2.7 install Visual C++ 2008 Express SP1.
+For Python 2.6 and 2.7 install the `Microsoft Visual C++ Compiler for Python 2.7`_
+
+.. _`Microsoft Visual C++ Compiler for Python 2.7`: https://www.microsoft.com/en-us/download/details.aspx?id=44266
 
 .. _install-no-c:
 
diff --git a/doc/tools.rst b/doc/tools.rst
@@ -77,7 +77,7 @@ uMongo
   Its inception comes from two needs: the lack of async ODM and the
   difficulty to do document (un)serialization with existing ODMs.
   Works with multiple drivers: PyMongo, TxMongo, motor_asyncio, and
-  mongomock.  The source `is on github
+  mongomock.  The source `is available on github
   <https://github.com/Scille/umongo>`_
 
 No longer maintained
diff --git a/setup.py b/setup.py
@@ -262,12 +262,16 @@ class custom_build_ext(build_ext):
     $ sudo yum install gcc python-devel
 
 If you are seeing this message on Microsoft Windows please install
-PyMongo using the MS Windows installer for your version of Python,
-available on pypi here:
+PyMongo using pip. Modern versions of pip will install PyMongo
+from binary wheels available on pypi. If you must install from
+source read the documentation here:
 
-http://pypi.python.org/pypi/pymongo/#downloads
+https://api.mongodb.com/python/current/installation.html#installing-from-source-on-windows
 
-If you are seeing this message on OSX please read the documentation
+If you are seeing this message on macOS / OSX please install PyMongo
+using pip. Modern versions of pip will install PyMongo from binary
+wheels available on pypi. If wheels are not available for your version
+of macOS / OSX, or you must install from source read the documentation
 here:
 
 http://api.mongodb.org/python/current/installation.html#osx
