INTPYTHON-380 Add doctests (#177)

Author: blink1073

.github/workflows/test-python.yml

@@ -32,8 +32,9 @@ jobs:
     - uses: extractions/setup-just@v2
     - run: just install
     - run: just lint
-    - run: just docs
     - run: uv run pre-commit run --hook-stage manual --all-files
+    - run: just docs
+    - run: just doctest
   build:
     runs-on: ${{ matrix.os }}
     strategy:

CONTRIBUTING.md

@@ -29,8 +29,6 @@ actual bugs and improvement requests.
 - All new features must include a test. Flask-PyMongo is tested against a
   matrix of all supported versions of Flask, PyMongo, and MongoDB, so tests
   ensure that your change works for all users.
-- There is also a `style` build. Please ensure your code conforms to
-  Flask-PyMongo's style rules with `tox -e style`
 - Use [Sphinx](http://www.sphinx-doc.org/en/master/)-style docstrings
 
 

docs/Makefile

@@ -30,7 +30,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named "sphinx.ext.*") or your custom ones.
-extensions = ["sphinx.ext.intersphinx", "sphinx.ext.autodoc"]
+extensions = ["sphinx.ext.intersphinx", "sphinx.ext.autodoc", "sphinx.ext.doctest"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/conf.py

@@ -65,9 +65,8 @@ versions.
 
 Flask-PyMongo is tested against `supported versions
 <https://www.mongodb.com/support-policy>`_ of MongoDB, and Python
-and 3.8+. For the exact list of version combinations that are tested and
-known to be compatible, see the `envlist` in `tox.ini
-<https://github.com/dcrosta/flask-pymongo/blob/master/tox.ini>`_.
+and 3.9+. For the exact list of version combinations that are tested and
+known to be compatible.
 
 
 Helpers
@@ -110,7 +109,7 @@ constructor. These are passed directly through to the underlying
     By default, Flask-PyMongo sets the ``connect`` keyword argument to
     ``False``, to prevent PyMongo from connecting immediately. PyMongo
     itself `is not fork-safe
-    <http://api.mongodb.com/python/current/faq.html#is-pymongo-fork-safe>`_,
+    <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/faq/#is-pymongo-fork-safe->`_,
     and delaying connection until the app is actually used is necessary to
     avoid issues. If you wish to change this default behavior, pass
     ``connect=True`` as a keyword argument to ``PyMongo``.

docs/index.rst

@@ -89,7 +89,4 @@ def save_upload(filename: str) -> str | Response:
 
 
 if __name__ == "__main__":
-    import doctest
-
-    doctest.testmod()
     app.run(debug=True)

docs/requirements.txt

@@ -109,7 +109,7 @@ def init_app(self, app: Flask, uri: str | None = None, *args: Any, **kwargs: Any
         database_name = parsed_uri["database"]
 
         # Try to delay connecting, in case the app is loaded before forking, per
-        # http://api.mongodb.com/python/current/faq.html#is-pymongo-fork-safe
+        # https://www.mongodb.com/docs/languages/python/pymongo-driver/current/faq/#is-pymongo-fork-safe-
         kwargs.setdefault("connect", False)
         if DriverInfo is not None:
             kwargs.setdefault("driver", DriverInfo("Flask-PyMongo", __version__))

examples/wiki/wiki.py

@@ -1,3 +1,6 @@
+docs_build := "docs/_build"
+sphinx_opts:= "-d " + docs_build + "/doctrees docs"
+
 # Default target executed when no arguments are given.
 [private]
 default:
@@ -15,7 +18,12 @@ lint:
 	uv run pre-commit run ruff-format --files
 
 docs:
-    uv run sphinx-build -T -b html docs docs/_build
+    uv run sphinx-build -T -b html {{sphinx_opts}} {{docs_build}}
+
+doctest:
+    uv run python -m doctest -v examples/wiki/wiki.py
+    uv run sphinx-build -E -b doctest {{sphinx_opts}} {{docs_build}}/doctest
+    uv run sphinx-build -b linkcheck {{sphinx_opts}} {{docs_build}}/linkcheck
 
 typing:
     uv run mypy --install-types --non-interactive .