PYTHON-3381 Improve readability of sphinx docs (#1156)

.pre-commit-config.yaml

@@ -24,7 +24,7 @@ repos:
     args: [--line-length=100]
 
 - repo: https://github.com/PyCQA/isort
-  rev: 5.10.1
+  rev: 5.12.0
   hooks:
   - id: isort
     files: \.py$

doc/changelog.rst

@@ -3519,9 +3519,3 @@ Changes in Version 0.9.7
   :class:`~pymongo.collection.Collection` names
 - add version as :attr:`pymongo.version`
 - add ``--no_ext`` command line option to *setup.py*
-
-.. toctree::
-   :hidden:
-
-   python3
-   examples/gevent

doc/common-issues.rst

@@ -3,8 +3,6 @@ Frequently Encountered Issues
 
 Also see the :ref:`TLSErrors` section.
 
-.. contents::
-
 Server reports wire version X, PyMongo requires Y
 -------------------------------------------------
 

doc/conf.py

@@ -32,7 +32,6 @@ try:
 except ImportError:
     pass
 
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -108,13 +107,18 @@ db = client.doctest_test
 
 # -- Options for HTML output ---------------------------------------------------
 
-# Theme gratefully vendored from CPython source.
-html_theme = "pydoctheme"
-html_theme_path = ["."]
-html_theme_options = {"collapsiblesidebar": True, "googletag": False}
+try:
+    import furo  # noqa
 
-# Additional static files.
-html_static_path = ["static"]
+    html_theme = "furo"
+except ImportError:
+    # Theme gratefully vendored from CPython source.
+    html_theme = "pydoctheme"
+    html_theme_path = ["."]
+    html_theme_options = {"collapsiblesidebar": True, "googletag": False}
+
+    # Additional static files.
+    html_static_path = ["static"]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".

doc/docs-requirements.txt

@@ -1,4 +1,5 @@
-Sphinx~=4.2
+Sphinx~=6.1
 sphinx_rtd_theme~=0.5
 readthedocs-sphinx-search~=0.1
 sphinxcontrib-shellcheck~=1.1
+furo==2022.12.7

doc/faq.rst

@@ -1,8 +1,6 @@
 Frequently Asked Questions
 ==========================
 
-.. contents::
-
 Is PyMongo thread-safe?
 -----------------------
 

doc/migrate-to-pymongo4.rst

@@ -3,8 +3,6 @@
 PyMongo 4 Migration Guide
 =========================
 
-.. contents::
-
 .. testsetup::
 
   from pymongo import MongoClient, ReadPreference

doc/python3.rst

@@ -1,8 +1,6 @@
 Python 3 FAQ
 ============
 
-.. contents::
-
 What Python 3 versions are supported?
 -------------------------------------