Add strings fields documentation

Author: insspb

docs/forms.md

@@ -48,8 +48,10 @@ For all fields, processed by Flask-Mongoengine integration:
   {attr}`validators` extension by Flask-Mongoengine.
 - If model field definition have {attr}`wtf_filters` defined, they will be forwarded to
   WTForm as {attr}`filters`.
-- If model field definition have {attr}`required`, then {class}`~wtforms.validators.InputRequired`
-  will be added to form {attr}`validators`, otherwise {class}`~wtforms.validators.Optional`
+- If model field definition have {attr}`required`, then
+  {class}`~wtforms.validators.InputRequired`
+  will be added to form {attr}`validators`, otherwise
+  {class}`~wtforms.validators.Optional`
   added.
 - If model field definition have {attr}`verbose_name` it will be used as form field
   {attr}`label`, otherwise pure field name used.
@@ -103,7 +105,53 @@ Not yet documented. Please help us with new pull request.
 
 ### EmailField
 
-Not yet documented. Please help us with new pull request.
+- API: {class}`.db_fields.EmailField`
+- Default form field class: {class}`~.MongoEmailField`
+
+#### Form generation behaviour
+
+Unlike [StringField] WTForm class of the field is not adjusted by normal form
+generation sequence and always match {class}`~.MongoEmailField`. All other
+adjustments, related to validators insert are work with EmailField in the same way,
+as in [StringField].
+
+Additional {class}`~wtforms.validators.Email` validator is also inserted to form
+field, to exclude unnecessary database request, if form data incorrect.
+
+Field respect user's adjustments in {attr}`wtf_field_class` option of
+{class}`.db_fields.EmailField`. This will change form field display, but will not
+change inserted validators.
+
+#### Examples
+
+strings_demo.py in example app contain basic non-requirement example. You can adjust
+it to any provided example for test purposes.
+
+##### Not required EmailField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    url_field = db.EmailField()
+````
+
+##### Required EmailField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    required_url_field = db.EmailField(required=True)
+````
 
 ### EmbeddedDocumentField
 
@@ -181,9 +229,169 @@ in another database fields too, but all of them based on
 - {class}`~.MongoTextAreaField`
 - {class}`~.MongoURLField`
 
+#### Examples
+
+strings_demo.py in example app contain basic non-requirement example. You can adjust
+it to any provided example for test purposes.
+
+##### Not limited StringField as MongoTextAreaField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    string_field = db.StringField()
+```
+
+##### Not limited StringField as MongoTelField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+from flask_mongoengine.wtf import fields as mongo_fields
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    tel_field = db.StringField(wtf_field_class=mongo_fields.MongoTelField)
+```
+
+##### Not limited StringField as MongoTextAreaField with https regex
+
+[mongoengine] and [wtforms] projects are not consistent in how they work with regex.
+You will be safe, if you use {func}`re.compile` each time, when you work with regex
+settings, before parent projects itself.
+
+```python
+"""strings_demo.py"""
+import re
+
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    regexp_string_field = db.StringField(regex=re.compile(
+        r"^(https:\/\/)[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=]+$"
+    ))
+```
+
+##### Size limited StringField as MongoStringField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    sized_string_field = db.StringField(min_length=5)
+```
+
+##### Required password field with minimum size
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+from flask_mongoengine.wtf import fields as mongo_fields
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    password_field = db.StringField(
+        wtf_field_class=mongo_fields.MongoPasswordField,
+        required=True,
+        min_length=5,
+    )
+```
+
 ### URLField
 
-Not yet documented. Please help us with new pull request.
+- API: {class}`.db_fields.URLField`
+- Default form field class: {class}`~.MongoURLField`
+
+#### Form generation behaviour
+
+Unlike [StringField] WTForm class of the field is not adjusted by normal form
+generation sequence and always match {class}`~.MongoURLField`. All other
+adjustments, related to validators insert are work with EmailField in the same way,
+as in [StringField].
+
+Additional {class}`~wtforms.validators.Regexp` validator is also inserted to form
+field, to exclude unnecessary database request, if form data incorrect. This
+validator use regexp, provided in {attr}`url_regex` of {class}`.db_fields.URLField`,
+or default URL regexp from [mongoengine] project. This is different from
+Flask-Mongoengine version **1.0.0** or earlier, where {class}`~wtforms.validators.URL`
+was inserted. This was changed, to exclude validators conflicts.
+
+```{important}
+{func}`~.model_form` is still use {class}`~wtforms.validators.URL` for
+compatibility with old setups.
+```
+
+Field respect user's adjustments in {attr}`wtf_field_class` option of
+{class}`.db_fields.URLField`. This will change form field display, but will not
+change inserted validators.
+
+#### Examples
+
+strings_demo.py in example app contain basic non-requirement example. You can adjust
+it to any provided example for test purposes.
+
+##### Not required URLField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    url_field = db.URLField()
+````
+
+##### Required URLField with minimum size
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    required_url_field = db.URLField(required=True, min_length=25)
+````
+
+##### URLField with https only regexp check, if data exist
+
+Regexp for {attr}`url_regex` should be prepared by {mod}`re`.
+
+```python
+"""strings_demo.py"""
+import re
+
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    https_url_field = db.URLField(
+        url_regex=re.compile(
+            r"^(https:\/\/)[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=]+$"
+        ),
+    )
+````
 
 ## Unsupported fields
 
@@ -282,7 +490,15 @@ Not yet documented. Please help us with new pull request.
 Not yet documented. Please help us with new pull request.
 
 [mongoengine]: https://docs.mongoengine.org/
+
 [supported fields]: #supported-fields
+
 [#379]: https://github.com/MongoEngine/flask-mongoengine/issues/379
+
 [integration]: forms
+
 [global transforms]: #global-transforms
+
+[stringfield]: #stringfield
+
+[wtforms]: https://wtforms.readthedocs.io/en/3.0.x/