Merge pull request #2530 from bagerard/fix_doc_formatting

fix doc formatting (enumfield, etc)

docs/apireference.rst

@@ -75,6 +75,7 @@ Fields
 .. autoclass:: mongoengine.fields.StringField
 .. autoclass:: mongoengine.fields.URLField
 .. autoclass:: mongoengine.fields.EmailField
+.. autoclass:: mongoengine.fields.EnumField
 .. autoclass:: mongoengine.fields.IntField
 .. autoclass:: mongoengine.fields.LongField
 .. autoclass:: mongoengine.fields.FloatField

docs/guide/defining-documents.rst

@@ -336,7 +336,6 @@ supplying the :attr:`reverse_delete_rule` attributes on the
 :class:`ReferenceField` definition, like this::
 
     class ProfilePage(Document):
-        ...
         employee = ReferenceField('Employee', reverse_delete_rule=mongoengine.CASCADE)
 
 The declaration in this example means that when an :class:`Employee` object is

mongoengine/connection.py

@@ -181,8 +181,7 @@ def register_connection(
 ):
     """Register the connection settings.
 
-    : param alias: the name that will be used to refer to this connection
+    :param alias: the name that will be used to refer to this connection throughout MongoEngine
-        throughout MongoEngine
     :param db: the name of the database to use, for compatibility with connect
     :param name: the name of the specific database to use
     :param host: the host name of the: program: `mongod` instance to connect to

mongoengine/context_managers.py

@@ -177,14 +177,28 @@ class query_counter:
     This was designed for debugging purpose. In fact it is a global counter so queries issued by other threads/processes
     can interfere with it
 
+    Usage:
+
+    .. code-block:: python
+
+        class User(Document):
+            name = StringField()
+
+        with query_counter() as q:
+            user = User(name='Bob')
+            assert q == 0       # no query fired yet
+            user.save()
+            assert q == 1       # 1 query was fired, an 'insert'
+            user_bis = User.objects().first()
+            assert q == 2       # a 2nd query was fired, a 'find_one'
+
     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://docs.mongodb.com/manual/tutorial/iterate-a-cursor/#cursor-batches)
     - Some queries are ignored by default by the counter (killcursors, db.system.indexes)
     """
 
     def __init__(self, alias=DEFAULT_CONNECTION_NAME):
-        """Construct the query_counter"""
         self.db = get_db(alias=alias)
         self.initial_profiling_level = None
         self._ctx_query_counter = 0  # number of queries issued by the context

mongoengine/fields.py

@@ -1611,11 +1611,14 @@ class EnumField(BaseField):
     """Enumeration Field. Values are stored underneath as is,
     so it will only work with simple types (str, int, etc) that
     are bson encodable
+
     Example usage:
+
     .. code-block:: python
 
         class Status(Enum):
             NEW = 'new'
+            ONGOING = 'ongoing'
             DONE = 'done'
 
         class ModelWithEnum(Document):
@@ -1625,13 +1628,18 @@ class EnumField(BaseField):
         ModelWithEnum(status=Status.DONE)
 
     Enum fields can be searched using enum or its value:
+
     .. code-block:: python
 
         ModelWithEnum.objects(status='new').count()
         ModelWithEnum.objects(status=Status.NEW).count()
 
-    Note that choices cannot be set explicitly, they are derived
+    The values can be restricted to a subset of the enum by using the ``choices`` parameter:
-    from the provided enum class.
+
+    .. code-block:: python
+
+        class ModelWithEnum(Document):
+            status = EnumField(Status, choices=[Status.NEW, Status.DONE])
     """
 
     def __init__(self, enum, **kwargs):

tests/fields/test_fields.py

@@ -2077,7 +2077,7 @@ class TestField(MongoDBTestCase):
         a ComplexBaseField.
         """
 
-        class EnumField(BaseField):
+        class SomeField(BaseField):
             def __init__(self, **kwargs):
                 super().__init__(**kwargs)
 
@@ -2088,7 +2088,7 @@ class TestField(MongoDBTestCase):
                 return tuple(value)
 
         class TestDoc(Document):
-            items = ListField(EnumField())
+            items = ListField(SomeField())
 
         TestDoc.drop_collection()