Dirty Models Sphinx extension¶
Sphinx extension for dirty models
About¶
Sphinx extension to help developers to write documentation of applications which use Dirty Models.
Features¶
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.
Changelog¶
Version 0.5.1¶
Fix regressions.
Version 0.5.0¶
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.
Version 0.4.1¶
Fix installation.
Version 0.4.0¶
Document default timezone on TimeField and DatetimeField.
Document forced timezone on DatetimeField.
Minor fixes.
Fix nested classes.
Document EnumField.
Version 0.3.0¶
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
.
Issues¶
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.
Installation¶
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'
]
Configuration¶
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.
Future¶
Document Dirty Validators.
Document basic validations.