Sphinx extension for dirty models
Sphinx extension to help developers to write documentation of applications which use Dirty Models.
- Describe each field with real type.
- All field types defined on Dirty Models are documented.
- Use prefixed (doc comment using
#:
before field) or suffixed (Multiline doc string after field) documentation for each field. - Document
read only
fields. - Document default value for each field.
- Document datetime format on those fields.
- Able to set a prefix text in model signature.
- Able to set a prefix text in fields signature.
- Able to document field type as annotation or as field directive.
- Able to add models to
toctree
. - Able to add model attributes to
toctree
. - Able to describe model as structure.
- Make it compatible with newer versions of Sphinx (+5.0).
- Remove deprecated dependencies in Sphinx 3.0.0.
- Added documentation for HashMapModels with hardcoded field type.
- Fixes.
- Use access_mode of Dirty Models version 0.12.0.
- Fix regressions.
- Added option to describe model as structure.
- Added enum documenter.
- Added option to hide/show alias.
- Added option to hide/show read-only tag.
- Added option to use custom title as model name.
- No document fields with key hidden set to true on field metadata.
- Better field type handling.
- New module autodocumenter autodirtymodule in order to allow to set new options at module level.
- Fix installation.
- Document default timezone on TimeField and DatetimeField.
- Document forced timezone on DatetimeField.
- Minor fixes.
- Fix nested classes.
- Document EnumField.
- Added option to add models to
toctree
. - Added option to add model attributes to
toctree
. - Added option to set prefix model signature.
- Added option to set prefix model field signature.
- Added option to use field type as annotation.
- Added fields to index.
- Changed default value label to
Default value
.
- Latex manual document class builder fails when model attributes are in
toctree
. That is because it creates a fake sections with sameids
and remove aftertoctree
is created. So, latex builder does not found references when it try to create links.
Just use pip
to install it:
$ pip install dirty-models-sphinx
And add to Sphinx extensions to your project.
Warning
autodoc extension (included in Sphinx) is required.
conf.py file:
extensions = [
'sphinx.ext.autodoc',
'dirty_models_sphinx'
]
It is possible to modify Dirty Models Sphinx extension behavior using configuration in conf.py
file.
dirty_model_add_classes_to_toc
If it is
True
Dirty Models classes will be added to table of content. Default:True
.
dirty_model_add_attributes_to_toc
If it is
True
Dirty Models class attributes will be added to table of content, only if classes were added. Default:True
.
dirty_model_class_label
It defines a prefix text for Dirty Model class signatures. It is possible to use
None
in order to avoid prefix. Default:'Model'
.
dirty_model_property_label
It defines a prefix text for Dirty Model class field signatures. It is possible to use
None
in order to avoid prefix. Default:'property'
.
dirty_enum_label
It defines a prefix text for enumearions signatures. It is possible to use
None
in order to avoid prefix. Default:'Enum'
.
dirty_model_hide_alias
It allows to hide field alias.
dirty_model_hide_readonly
It allows to hide read-only tags.
Just use regular autodocumenter:
.. automodule:: models
:members:
:show-inheritance:
- Document Dirty Validators.
- Document basic validations.