Fix doc warnings

docs/changelog.rst

@@ -12,9 +12,11 @@ Development
 - Fix querying GenericReferenceField with __in operator #2886
 - Fix Document.compare_indexes() not working correctly for text indexes on multiple fields #2612
 - Add support for transaction through run_in_transaction (kudos to juannyG for this) #2569
+
   Some considerations:
+
     - make sure to read https://www.mongodb.com/docs/manual/core/transactions-in-applications/#callback-api-vs-core-api
-    - run_in_transaction context manager relies on Pymongo coreAPI, it will retry automatically in case of `UnknownTransactionCommitResult` but not `TransientTransactionError` exceptions
+    - run_in_transaction context manager relies on Pymongo coreAPI, it will retry automatically in case of ``UnknownTransactionCommitResult`` but not ``TransientTransactionError`` exceptions
     - Using .count() in a transaction will always use Collection.count_document (as estimated_document_count is not supported in transactions)
 - BREAKING CHANGE: wrap _document_registry (normally not used by end users) with _DocumentRegistry which acts as a singleton to access the registry
 - Log a warning in case users creates multiple Document classes with the same name as it can lead to unexpected behavior #1778
@@ -222,12 +224,13 @@ Changes in 0.19.1
 =================
 - Tests require Pillow < 7.0.0 as it dropped Python2 support
 - DEPRECATION: The interface of ``QuerySet.aggregate`` method was changed, it no longer takes an unpacked list of
-    pipeline steps (*pipeline) but simply takes the pipeline list just like ``pymongo.Collection.aggregate`` does. #2079
+  pipeline steps (``*pipeline``) but simply takes the pipeline list just like ``pymongo.Collection.aggregate`` does. #2079
 
 Changes in 0.19.0
 =================
 - BREAKING CHANGE: ``class_check`` and ``read_preference`` keyword arguments are no longer available when filtering a ``QuerySet``. #2112
-    - Instead of ``Doc.objects(foo=bar, read_preference=...)`` use ``Doc.objects(foo=bar).read_preference(...)``.
+
+  - Instead of ``Doc.objects(foo=bar, read_preference=...)`` use ``Doc.objects(foo=bar).read_preference(...)``.
     - Instead of ``Doc.objects(foo=bar, class_check=False)`` use ``Doc.objects(foo=bar).clear_cls_query(...)``.
     - This change also renames the private ``QuerySet._initial_query`` attribute to ``_cls_query``.
 - BREAKING CHANGE: Removed the deprecated ``format`` param from ``QuerySet.explain``. #2113
@@ -494,7 +497,7 @@ Changes in 0.10.0
 - Added support for specifying authentication source as option ``authSource`` in URI. #967
 - Fixed mark_as_changed to handle higher/lower level fields changed. #927
 - ListField of embedded docs doesn't set the _instance attribute when iterating over it #914
-- Support += and *= for ListField #595
+- Support ``+=`` and ``*=`` for ListField #595
 - Use sets for populating dbrefs to dereference
 - Fixed unpickled documents replacing the global field's list. #888
 - Fixed storage of microseconds in ComplexDateTimeField and unused separator option. #910

docs/conf.py

@@ -32,7 +32,7 @@
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = {".rst": "restructuredtext"}
 
 # The encoding of source files.
 # source_encoding = 'utf-8'

docs/guide/defining-documents.rst

@@ -577,7 +577,7 @@ but are not limited to:
 
 .. note::
 
-    Additional options are forwarded as **kwargs to pymongo's create_index method.
+    Additional options are forwarded as ``**kwargs`` to pymongo's create_index method.
     Inheritance adds extra fields indices see: :ref:`document-inheritance`.
 
 Global index default options

mongoengine/base/document.py

@@ -467,6 +467,7 @@ def from_json(cls, json_data, created=False, **kwargs):
         :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).
             * If False and an ID is NOT provided, consider the document as

mongoengine/base/fields.py

@@ -79,13 +79,13 @@ def __init__(
         :param choices: (optional) The valid choices
         :param null: (optional) If the field value can be null when a default exists. If not set, the default value
             will be used in case a field with a default value is set to None. Defaults to False.
-        :param sparse: (optional) `sparse=True` combined with `unique=True` and `required=False`
-            means that uniqueness won't be enforced for `None` values (Creates an index). Defaults to False.
-        :param **kwargs: (optional) Arbitrary indirection-free metadata for
+        :param sparse: (optional) ``sparse=True`` combined with ``unique=True`` and ``required=False``
+            means that uniqueness won't be enforced for ``None`` values (Creates an index). Defaults to False.
+        :param kwargs: (optional) Arbitrary indirection-free metadata for
             this field can be supplied as additional keyword arguments and
             accessed as attributes of the field. Must not conflict with any
-            existing attributes. Common metadata includes `verbose_name` and
-            `help_text`.
+            existing attributes. Common metadata includes ``verbose_name`` and
+            ``help_text``.
         """
         self.db_field = db_field if not primary_key else "_id"
 

mongoengine/queryset/base.py

@@ -682,8 +682,7 @@ def update_one(
             updated items
         :param array_filters: A list of filters specifying which array elements an update should apply.
         :param update: Django-style update keyword arguments
-            full_result
-        :returns the number of updated documents (unless ``full_result`` is True)
+        :returns: the number of updated documents (unless ``full_result`` is True)
         """
         return self.update(
             upsert=upsert,
@@ -904,7 +903,7 @@ def limit(self, n):
         achieved using array-slicing syntax (e.g. ``User.objects[:5]``).
 
         :param n: the maximum number of objects to return if n is greater than 0.
-        When 0 is passed, returns all the documents in the cursor
+            When 0 is passed, returns all the documents in the cursor
         """
         queryset = self.clone()
         queryset._limit = n
@@ -955,18 +954,21 @@ def collation(self, collation=None):
         """
         Collation allows users to specify language-specific rules for string
         comparison, such as rules for lettercase and accent marks.
-        :param collation: `~pymongo.collation.Collation` or dict with
-        following fields:
-            {
-                locale: str,
-                caseLevel: bool,
-                caseFirst: str,
-                strength: int,
-                numericOrdering: bool,
-                alternate: str,
-                maxVariable: str,
-                backwards: str
-            }
+
+        :param collation: ``~pymongo.collation.Collation`` or dict with
+            following fields::
+
+                {
+                    locale: str,
+                    caseLevel: bool,
+                    caseFirst: str,
+                    strength: int,
+                    numericOrdering: bool,
+                    alternate: str,
+                    maxVariable: str,
+                    backwards: str
+                }
+
         Collation should be added to indexes like in test example
         """
         queryset = self.clone()