Merge pull request #2832 from bagerard/improve_doc_and_upgrade_docs_deps

bagerard · web-flow · commit d600932a2bc4 · 2024-08-25T23:58:40.000+02:00
upgrade docs deps + fix inconsistencies
diff --git a/.github/workflows/github-actions.yml b/.github/workflows/github-actions.yml
@@ -123,7 +123,7 @@ jobs:
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v4
       with:
-        python-version: 3.7
+        python-version: 3.9
         check-latest: true
     - name: install python dep
       run: |
diff --git a/README.rst b/README.rst
@@ -48,7 +48,7 @@ You may also have `setuptools <http://peak.telecommunity.com/DevCenter/setuptool
 and thus you can use ``easy_install -U mongoengine``. Another option is
 `pipenv <https://docs.pipenv.org/>`_. You can then use ``pipenv install mongoengine``
 to both create the virtual environment and install the package. Otherwise, you can
-download the source from `GitHub <http://github.com/MongoEngine/mongoengine>`_ and
+download the source from `GitHub <https://github.com/MongoEngine/mongoengine>`_ and
 run ``python setup.py install``.
 
 The support for Python2 was dropped with MongoEngine 0.20.0
diff --git a/docs/Makefile b/docs/Makefile
@@ -16,13 +16,10 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html-readthedocs to simulate an html-build for readthedocs"
 	@echo "  html      to make standalone HTML files"
 	@echo "  dirhtml   to make HTML files named index.html in directories"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  qthelp    to make HTML files and a qthelp project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  changes   to make an overview of all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
 	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
@@ -40,47 +37,20 @@ html:
 
 html-readthedocs:
 	$(SPHINXBUILD) -T -E -b readthedocs $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
+	@echo "Open in browser: file://`realpath $(BUILDDIR)/html/index.html`"
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
 htmlhelp:
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MongoEngine.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MongoEngine.qhc"
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
 changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
diff --git a/docs/django.rst b/docs/django.rst
@@ -3,17 +3,4 @@ Django Support
 ==============
 
 .. note:: Django support has been split from the main MongoEngine
-    repository. The *legacy* Django extension may be found bundled with the
-    0.9 release of MongoEngine.
-
-
-
-Help Wanted!
-------------
-
-The MongoEngine team is looking for help contributing and maintaining a new
-Django extension for MongoEngine! If you have Django experience and would like
-to help contribute to the project, please get in touch on the
-`mailing list <http://groups.google.com/group/mongoengine-users>`_ or by
-simply contributing on
-`GitHub <https://github.com/MongoEngine/django-mongoengine>`_.
+    repository.
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -8,5 +8,5 @@ Does MongoEngine support asynchronous drivers (Motor, TxMongo)?
 No, MongoEngine is exclusively based on PyMongo and isn't designed to support other driver.
 If this is a requirement for your project, check the alternative:  `uMongo`_ and `MotorEngine`_.
 
-.. _uMongo: https://umongo.readthedocs.io/
-.. _MotorEngine: https://motorengine.readthedocs.io/
+.. _uMongo: https://umongo.readthedocs.io/en/latest/
+.. _MotorEngine: https://motorengine.readthedocs.io/en/latest/
diff --git a/docs/guide/connecting.rst b/docs/guide/connecting.rst
@@ -47,7 +47,7 @@ of the MongoDB connection string is for::
     connect(host="mongodb://my_user:my_password@127.0.0.1:27017/my_db?authSource=my_db")
 
 The URI string can also be used to configure advanced parameters like ssl, replicaSet, etc. For more
-information or example about URI string, you can refer to the `official doc <https://docs.mongodb.com/manual/reference/connection-string/>`_::
+information or example about URI string, you can refer to the `official doc <https://www.mongodb.com/docs/manual/reference/connection-string/>`_::
 
     connect(host="mongodb://my_user:my_password@127.0.0.1:27017/my_db?authSource=admin&ssl=true&replicaSet=globaldb")
 
diff --git a/docs/guide/defining-documents.rst b/docs/guide/defining-documents.rst
@@ -29,7 +29,7 @@ documents are serialized based on their field order.
 
 .. _dynamic-document-schemas:
 
-Dynamic document schemas
+Dynamic Document Schemas
 ========================
 One of the benefits of MongoDB is dynamic schemas for a collection, whilst data
 should be planned and organised (after all explicit is better than implicit!)
@@ -260,7 +260,7 @@ document class as the first argument::
     comment2 = Comment(content='Nice article!')
     page = Page(comments=[comment1, comment2])
 
-Embedded documents can also leverage the flexibility of :ref:`dynamic-document-schemas:`
+Embedded documents can also leverage the flexibility of :ref:`dynamic-document-schemas`
 by inheriting :class:`~mongoengine.DynamicEmbeddedDocument`.
 
 Dictionary Fields
@@ -325,7 +325,7 @@ as the constructor's argument::
 .. _many-to-many-with-listfields:
 
 Many to Many with ListFields
-'''''''''''''''''''''''''''
+''''''''''''''''''''''''''''
 
 If you are implementing a many to many relationship via a list of references,
 then the references are stored as DBRefs and to query you need to pass an
@@ -492,7 +492,7 @@ The following example shows a :class:`Log` document that will be limited to
         meta = {'max_documents': 1000, 'max_size': 2000000}
 
 Timeseries collections
-------------------
+----------------------
 A :class:`~mongoengine.Document` may use a **Timeseries Collection** by specifying
 :attr:`timeseries` in the :attr:`meta` dictionary. Timeseries collection were added
 in MongoDB 5.0 (`doc <https://www.mongodb.com/docs/v5.3/core/timeseries-collections/>`_).
@@ -599,7 +599,7 @@ There are a few top level defaults for all indexes that can be set::
 
 
 :attr:`index_opts` (Optional)
-    Set any default index options - see the `full options list <https://docs.mongodb.com/manual/reference/method/db.collection.createIndex/#db.collection.createIndex>`_
+    Set any default index options - see the `full options list <https://www.mongodb.com/docs/manual/reference/method/db.collection.createIndex/>`_
 
 :attr:`index_background` (Optional)
     Set the default value for if an index should be indexed in the background
diff --git a/docs/guide/gridfs.rst b/docs/guide/gridfs.rst
@@ -9,7 +9,7 @@ GridFS support comes in the form of the :class:`~mongoengine.fields.FileField` f
 object. This field acts as a file-like object and provides a couple of
 different ways of inserting and retrieving data. Arbitrary metadata such as
 content type can also be stored alongside the files. The object returned when accessing a
-FileField is a proxy to `Pymongo's GridFS <https://api.mongodb.com/python/current/examples/gridfs.html#gridfs-example>`_
+FileField is a proxy to `Pymongo's GridFS <https://pymongo.readthedocs.io/en/stable/examples/gridfs.html#gridfs-example>`_
 In the following example, a document is created to store details about animals, including a photo::
 
     class Animal(Document):
diff --git a/docs/guide/installing.rst b/docs/guide/installing.rst
@@ -2,7 +2,7 @@
 Installing MongoEngine
 ======================
 
-To use MongoEngine, you will need to download `MongoDB <http://mongodb.com/>`_
+To use MongoEngine, you will need to download `MongoDB <https://www.mongodb.com/>`_
 and ensure it is running in an accessible location. You will also need
 `PyMongo <http://api.mongodb.org/python>`_ to use MongoEngine, but if you
 install MongoEngine using setuptools, then the dependencies will be handled for
@@ -22,7 +22,7 @@ Alternatively, if you don't have setuptools installed, `download it from PyPi
     $ python setup.py install
 
 To use the bleeding-edge version of MongoEngine, you can get the source from
-`GitHub <http://github.com/mongoengine/mongoengine/>`_ and install it as above:
+`GitHub <https://github.com/MongoEngine/mongoengine/>`_ and install it as above:
 
 .. code-block:: console
 
diff --git a/docs/guide/migration.rst b/docs/guide/migration.rst
@@ -262,7 +262,7 @@ If you would remove the 'name' field or its index, you would have to call:
     User._get_collection().drop_index('name_1')
 
 .. note:: When adding new fields or new indexes, MongoEngine will take care of creating them
-    (unless `auto_create_index` is disabled) ::
+    (unless `auto_create_index` is disabled)
 
 Recommendations
 ===============
diff --git a/docs/guide/mongomock.rst b/docs/guide/mongomock.rst
@@ -5,7 +5,7 @@ Use mongomock for testing
 Although we recommend running your tests against a regular MongoDB server, it is sometimes useful to plug
 MongoEngine to alternative implementations (mongomock, montydb, mongita, etc).
 
-`mongomock <https://github.com/vmalloc/mongomock/>`_ is historically the one suggested for MongoEngine and is
+`mongomock <https://github.com/mongomock/mongomock>`_ is historically the one suggested for MongoEngine and is
 a package to do just what the name implies, mocking a mongo database.
 
 To use with mongoengine, simply specify mongomock when connecting with
diff --git a/docs/guide/querying.rst b/docs/guide/querying.rst
@@ -241,7 +241,7 @@ Update with Aggregation Pipeline
 It is possible to provide a raw :mod:`PyMongo` aggregation update parameter, which will
 be integrated directly into the update. This is done by using ``__raw__`` keyword argument to the update method
 and provide the pipeline as a list
-`Update with Aggregation Pipeline <https://docs.mongodb.com/manual/reference/method/db.collection.updateMany/#update-with-aggregation->`_
+`Update with Aggregation Pipeline <https://www.mongodb.com/docs/manual/reference/method/db.collection.updateMany/#update-with-aggregation->`_
 ::
 
     # 'tags' field is set to 'coding is fun'
@@ -257,7 +257,7 @@ Update with Array Operator
 It is possible to update specific value in array by use array_filters (arrayFilters) operator.
 This is done by using ``__raw__`` keyword argument to the update method and provide the arrayFilters as a list.
 
-`Update with Array Operator <https://www.mongodb.com/docs/manual/reference/operator/update/positional-filtered->`_
+`Update with Array Operator <https://www.mongodb.com/docs/manual/reference/operator/update/positional-filtered/>`_
 ::
 
     # assuming an initial 'tags' field == ['test1', 'test2', 'test3']
@@ -447,7 +447,7 @@ would be generating "tag-clouds"::
 
 MongoDB aggregation API
 -----------------------
-If you need to run aggregation pipelines, MongoEngine provides an entry point to `Pymongo's aggregation framework <https://api.mongodb.com/python/current/examples/aggregation.html#aggregation-framework>`_
+If you need to run aggregation pipelines, MongoEngine provides an entry point to `Pymongo's aggregation framework <https://pymongo.readthedocs.io/en/stable/examples/aggregation.html#aggregation-framework>`_
 through :meth:`~mongoengine.queryset.QuerySet.aggregate`. Check out Pymongo's documentation for the syntax and pipeline.
 An example of its use would be::
 
@@ -661,7 +661,7 @@ to push values with index::
 .. note::
     Currently only top level lists are handled, future versions of mongodb /
     pymongo plan to support nested positional operators.  See `The $ positional
-    operator <https://docs.mongodb.com/manual/tutorial/update-documents/#Updating-The%24positionaloperator>`_.
+    operator <https://www.mongodb.com/docs/manual/tutorial/update-documents/#Updating-The%24positionaloperator>`_.
 
 Server-side javascript execution
 ================================
diff --git a/docs/index.rst b/docs/index.rst
@@ -20,9 +20,6 @@ MongoDB. To install it, simply run
 :doc:`apireference`
   The complete API documentation --- the innards of documents, querysets and fields.
 
-:doc:`upgrade`
-  How to upgrade MongoEngine.
-
 :doc:`faq`
   Frequently Asked Questions
 
@@ -33,7 +30,7 @@ MongoDB and driver support
 --------------------------
 
 MongoEngine is based on the PyMongo driver and tested against multiple versions of MongoDB.
-For further details, please refer to the `readme <https://github.com/MongoEngine/mongoengine#mongoengine>`_.
+For further details, please refer to the `readme <https://github.com/MongoEngine/mongoengine>`_.
 
 Community
 ---------
@@ -47,22 +44,18 @@ Contributing
 
 **Yes please!**  We are always looking for contributions, additions and improvements.
 
-The source is available on `GitHub <http://github.com/MongoEngine/mongoengine>`_
+The source is available on `GitHub <https://github.com/MongoEngine/mongoengine>`_
 and contributions are always encouraged. Contributions can be as simple as
 minor tweaks to this documentation, the website or the core.
 
 To contribute, fork the project on
-`GitHub <http://github.com/MongoEngine/mongoengine>`_ and send a
+`GitHub <https://github.com/MongoEngine/mongoengine>`_ and send a
 pull request.
 
 Changes
 -------
 
-See the :doc:`changelog` for a full list of changes to MongoEngine and
-:doc:`upgrade` for upgrade information.
-
-.. note::  Always read and test the `upgrade <upgrade>`_ documentation before
-    putting updates live in production **;)**
+See the :doc:`changelog` for a full list of changes to MongoEngine.
 
 Offline Reading
 ---------------
@@ -81,7 +74,6 @@ formats for offline reading.
     guide/index
     apireference
     changelog
-    upgrade
     faq
     django
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,5 @@
-Sphinx==3.3.0
-sphinx-rtd-theme==0.5.0
-readthedocs-sphinx-ext==2.1.1
-docutils==0.17.1
-Jinja2<3.1
+Sphinx==7.4.7
+sphinx-rtd-theme==2.1.0rc2
+readthedocs-sphinx-ext==2.2.5
+docutils==0.20.1
+Jinja2==3.1.4
diff --git a/mongoengine/base/document.py b/mongoengine/base/document.py
@@ -461,13 +461,13 @@ def to_json(self, *args, **kwargs):
 
     @classmethod
     def from_json(cls, json_data, created=False, **kwargs):
-        """Converts json data to a Document instance
+        """Converts json data to a Document instance.
 
-        :param str json_data: The json data to load into the Document
+        :param str json_data: The json data to load into the Document.
         :param bool created: Boolean defining whether to consider the newly
             instantiated document as brand new or as persisted already:
             * If True, consider the document as brand new, no matter what data
-              it's loaded with (i.e. even if an ID is loaded).
+              it's loaded with (i.e., even if an ID is loaded).
             * If False and an ID is NOT provided, consider the document as
               brand new.
             * If False and an ID is provided, assume that the object has
diff --git a/mongoengine/context_managers.py b/mongoengine/context_managers.py
@@ -215,7 +215,7 @@ class User(Document):
 
     Be aware that:
 
-    - Iterating over large amount of documents (>101) makes pymongo issue `getmore` queries to fetch the next batch of documents (https://docs.mongodb.com/manual/tutorial/iterate-a-cursor/#cursor-batches)
+    - Iterating over large amount of documents (>101) makes pymongo issue `getmore` queries to fetch the next batch of documents (https://www.mongodb.com/docs/manual/tutorial/iterate-a-cursor/#cursor-batches)
     - Some queries are ignored by default by the counter (killcursors, db.system.indexes)
     """
 
diff --git a/mongoengine/fields.py b/mongoengine/fields.py
@@ -2065,7 +2065,7 @@ def __init__(
 
 class SequenceField(BaseField):
     """Provides a sequential counter see:
-     https://docs.mongodb.com/manual/reference/method/ObjectId/#ObjectIDs-SequenceNumbers
+     https://www.mongodb.com/docs/manual/reference/method/ObjectId/#ObjectIDs-SequenceNumbers
 
     .. note::
 
diff --git a/mongoengine/queryset/base.py b/mongoengine/queryset/base.py
@@ -405,7 +405,7 @@ def count(self, with_limit_and_skip=False):
             getting the count
         """
         # mimic the fact that setting .limit(0) in pymongo sets no limit
-        # https://docs.mongodb.com/manual/reference/method/cursor.limit/#zero-value
+        # https://www.mongodb.com/docs/manual/reference/method/cursor.limit/#zero-value
         if (
             self._limit == 0
             and with_limit_and_skip is False
@@ -963,7 +963,7 @@ def batch_size(self, size):
         """Limit the number of documents returned in a single batch (each
         batch requires a round trip to the server).
 
-        See http://api.mongodb.com/python/current/api/pymongo/cursor.html#pymongo.cursor.Cursor.batch_size
+        See https://pymongo.readthedocs.io/en/stable/api/pymongo/cursor.html#pymongo.cursor.Cursor
         for details.
 
         :param size: desired size of each batch.
@@ -1197,7 +1197,7 @@ def clear_cls_query(self):
     def comment(self, text):
         """Add a comment to the query.
 
-        See https://docs.mongodb.com/manual/reference/method/cursor.comment/#cursor.comment
+        See https://www.mongodb.com/docs/manual/reference/method/cursor.comment/
         for details.
         """
         return self._chainable_method("comment", text)
@@ -1341,7 +1341,7 @@ def aggregate(self, pipeline, *suppl_pipeline, **kwargs):
         :param suppl_pipeline: unpacked list of pipeline (added to support deprecation of the old interface)
             parameter will be removed shortly
         :param kwargs: (optional) kwargs dictionary to be passed to pymongo's aggregate call
-            See https://api.mongodb.com/python/current/api/pymongo/collection.html#pymongo.collection.Collection.aggregate
+            See https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.aggregate
         """
         using_deprecated_interface = isinstance(pipeline, dict) or bool(suppl_pipeline)
         user_pipeline = [pipeline] if isinstance(pipeline, dict) else list(pipeline)
@@ -1364,7 +1364,7 @@ def aggregate(self, pipeline, *suppl_pipeline, **kwargs):
             initial_pipeline.append({"$sort": dict(self._ordering)})
 
         if self._limit is not None:
-            # As per MongoDB Documentation (https://docs.mongodb.com/manual/reference/operator/aggregation/limit/),
+            # As per MongoDB Documentation (https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit/),
             # keeping limit stage right after sort stage is more efficient. But this leads to wrong set of documents
             # for a skip stage that might succeed these. So we need to maintain more documents in memory in such a
             # case (https://stackoverflow.com/a/24161461).
@@ -1401,7 +1401,7 @@ def map_reduce(
                          :class:`~bson.code.Code` or string
         :param output: output collection name, if set to 'inline' will return
            the results inline. This can also be a dictionary containing output options
-           see: http://docs.mongodb.org/manual/reference/command/mapReduce/#dbcmd.mapReduce
+           see: https://www.mongodb.com/docs/manual/reference/command/mapReduce/#mongodb-dbcommand-dbcmd.mapReduce
         :param finalize_f: finalize function, an optional function that
                            performs any post-reduction processing.
         :param scope: values to insert into map/reduce global scope. Optional.
