reorganize docs into sections for easier navigation part 1

docs/fields/common-parameters.md

@@ -0,0 +1,126 @@
+# Common Parameters
+
+All `Field` types have a set of common parameters.
+
+## primary_key
+
+`primary_key`: `bool` = `False` -> by default False.
+
+Sets the primary key column on a table, foreign keys always refer to the pk of the `Model`.
+
+Used in sql only.
+
+## autoincrement
+
+`autoincrement`: `bool` = `primary_key and type == int` -> defaults to True if column is a primary key and of type Integer, otherwise False.
+
+Can be only used with int/bigint fields.
+
+If a field has autoincrement it becomes optional.
+
+Used both in sql and pydantic (changes pk field to optional for autoincrement).
+
+## nullable
+
+`nullable`: `bool` = `not primary_key` -> defaults to False for primary key column, and True for all other. 
+
+Specifies if field is optional or required, used both with sql and pydantic.
+
+!!!note
+    By default all `ForeignKeys` are also nullable, meaning the related `Model` is not required.
+    
+    If you change the `ForeignKey` column to `nullable=False`, it becomes required.
+    
+
+!!!info
+    If you want to know more about how you can preload related models during queries and how the relations work read the [queries][queries] and [relations][relations] sections. 
+
+
+## default
+
+`default`: `Any` = `None` -> defaults to None. 
+
+A default value used if no other value is passed.
+
+In sql invoked on an insert, used during pydantic model definition.
+
+If the field has a default value it becomes optional.
+
+You can pass a static value or a Callable (function etc.)
+
+Used both in sql and pydantic.
+
+## server default
+
+`server_default`: `Any` = `None`  -> defaults to None. 
+
+A default value used if no other value is passed.
+
+In sql invoked on the server side so you can pass i.e. sql function (like now() or query/value wrapped in sqlalchemy text() clause).
+
+If the field has a server_default value it becomes optional.
+
+You can pass a static value or a Callable (function etc.)
+
+Used in sql only.
+
+Sample usage:
+
+```Python hl_lines="21-23"
+--8<-- "../docs_src/fields/docs004.py"
+```
+
+!!!warning
+    `server_default` accepts `str`, `sqlalchemy.sql.elements.ClauseElement` or `sqlalchemy.sql.elements.TextClause`
+    so if you want to set i.e. Integer value you need to wrap it in `sqlalchemy.text()` function like above
+
+!!!tip
+    You can pass also valid sql (dialect specific) wrapped in `sqlalchemy.text()`
+    
+    For example `func.now()` above could be exchanged for `text('(CURRENT_TIMESTAMP)')` for sqlite backend
+
+!!!info
+    `server_default` is passed straight to sqlalchemy table definition so you can read more in [server default][server default] sqlalchemy documentation
+ 
+## index
+
+`index`: `bool` = `False` -> by default False, 
+
+Sets the index on a table's column.
+
+Used in sql only.
+
+## unique
+
+`unique`: `bool` = `False` 
+
+Sets the unique constraint on a table's column.
+
+Used in sql only.
+
+## pydantic_only
+
+`pydantic_only`: `bool` = `False` 
+
+Prevents creation of a sql column for given field.
+
+Used for data related to given model but not to be stored in the database.
+
+Used in pydantic only.
+
+## choices
+
+`choices`: `Sequence` = `[]` 
+
+A set of choices allowed to be used for given field.
+
+Used for data validation on pydantic side.
+
+Prevents insertion of value not present in the choices list.
+
+Used in pydantic only.
+
+[relations]: ../relations/index.md
+[queries]: ../queries.md
+[pydantic]: https://pydantic-docs.helpmanual.io/usage/types/#constrained-types
+[server default]: https://docs.sqlalchemy.org/en/13/core/defaults.html#server-invoked-ddl-explicit-default-expressions

docs/fields/field-types.md

@@ -0,0 +1,151 @@
+# Fields
+
+
+There are 12 basic model field types and a special `ForeignKey` and `Many2Many` fields to establish relationships between models.
+
+!!!tip
+    For explanation of `ForeignKey` and `Many2Many` fields check [relations][relations].
+
+
+Each of the `Fields` has assigned both `sqlalchemy` column class and python type that is used to create `pydantic` model.
+
+
+## Fields Types
+
+### String
+
+`String(max_length, 
+        allow_blank: bool = True,
+        strip_whitespace: bool = False,
+        min_length: int = None,
+        max_length: int = None,
+        curtail_length: int = None,
+        regex: str = None,)` has a required `max_length` parameter.  
+
+* Sqlalchemy column: `sqlalchemy.String`  
+* Type (used for pydantic): `str` 
+
+!!!tip
+    For explanation of other parameters check [pydantic][pydantic] documentation.
+
+### Text
+
+`Text(allow_blank: bool = True, strip_whitespace: bool = False)` has no required parameters.  
+
+* Sqlalchemy column: `sqlalchemy.Text`  
+* Type (used for pydantic): `str` 
+
+!!!tip
+    For explanation of other parameters check [pydantic][pydantic] documentation.
+
+### Boolean
+
+`Boolean()` has no required parameters.  
+
+* Sqlalchemy column: `sqlalchemy.Boolean`  
+* Type (used for pydantic): `bool` 
+
+### Integer
+
+`Integer(minimum: int = None,
+        maximum: int = None,
+        multiple_of: int = None)` has no required parameters.  
+
+* Sqlalchemy column: `sqlalchemy.Integer`  
+* Type (used for pydantic): `int` 
+
+!!!tip
+    For explanation of other parameters check [pydantic][pydantic] documentation.
+
+### BigInteger
+
+`BigInteger(minimum: int = None,
+        maximum: int = None,
+        multiple_of: int = None)` has no required parameters.  
+
+* Sqlalchemy column: `sqlalchemy.BigInteger`  
+* Type (used for pydantic): `int` 
+
+!!!tip
+    For explanation of other parameters check [pydantic][pydantic] documentation.
+
+### Float
+
+`Float(minimum: float = None,
+        maximum: float = None,
+        multiple_of: int = None)` has no required parameters.  
+
+* Sqlalchemy column: `sqlalchemy.Float`  
+* Type (used for pydantic): `float` 
+
+!!!tip
+    For explanation of other parameters check [pydantic][pydantic] documentation.
+
+### Decimal
+
+`Decimal(minimum: float = None,
+        maximum: float = None,
+        multiple_of: int = None,
+        precision: int = None,
+        scale: int = None,
+        max_digits: int = None,
+        decimal_places: int = None)` has no required parameters
+        
+You can use either `length` and `precision` parameters or `max_digits` and `decimal_places`.  
+
+* Sqlalchemy column: `sqlalchemy.DECIMAL`  
+* Type (used for pydantic): `decimal.Decimal` 
+
+!!!tip
+    For explanation of other parameters check [pydantic][pydantic] documentation.
+
+### Date
+
+`Date()` has no required parameters.  
+
+* Sqlalchemy column: `sqlalchemy.Date`  
+* Type (used for pydantic): `datetime.date` 
+
+### Time
+
+`Time()` has no required parameters.  
+
+* Sqlalchemy column: `sqlalchemy.Time`  
+* Type (used for pydantic): `datetime.time` 
+
+### DateTime
+
+`DateTime()` has no required parameters.  
+
+* Sqlalchemy column: `sqlalchemy.DateTime`  
+* Type (used for pydantic): `datetime.datetime` 
+
+### JSON
+
+`JSON()` has no required parameters.  
+
+* Sqlalchemy column: `sqlalchemy.JSON`  
+* Type (used for pydantic): `pydantic.Json` 
+
+### UUID
+
+`UUID(uuid_format: str = 'hex')` has no required parameters.  
+
+* Sqlalchemy column: `ormar.UUID` based on `sqlalchemy.CHAR(36)` or `sqlalchemy.CHAR(32)` field (for string or hex format respectively)  
+* Type (used for pydantic): `uuid.UUID` 
+
+`uuid_format` parameters allow 'hex'(default) or 'string' values.
+
+Depending on the format either 32 or 36 char is used in the database.
+
+Sample:
+
+*  'hex' format value = `c616ab438cce49dbbf4380d109251dce` (CHAR(32))
+*  'string' value = `c616ab43-8cce-49db-bf43-80d109251dce` (CHAR(36))  
+
+When loaded it's always python UUID so you can compare it and compare two formats values between each other.
+
+[relations]: ../relations/index.md
+[queries]: ../queries.md
+[pydantic]: https://pydantic-docs.helpmanual.io/usage/types/#constrained-types
+[server default]: https://docs.sqlalchemy.org/en/13/core/defaults.html#server-invoked-ddl-explicit-default-expressions