Metadata-Version: 2.1
Name: sphinx-autoschematics
Version: 0.2.0
Summary: sphinx-autoschematics provides sphinx extensions for documenting schematics models
Home-page: https://github.com/NerdWalletOSS/sphinx-autoschematics
Author: Evan Borgstrom
Author-email: evan@borgstrom.ca
License: Apache License Version 2.0
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.6, <4
Description-Content-Type: text/markdown
Provides-Extra: test
License-File: LICENSE.txt

# sphinx-autoschematics

![Build Status](https://img.shields.io/travis/NerdWalletOSS/sphinx-autoschematics.svg)
![CodeCov](https://img.shields.io/codecov/c/github/NerdWalletOSS/sphinx-autoschematics.svg)
![PyPI - Version](https://img.shields.io/pypi/v/sphinx-autoschematics.svg)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sphinx-autoschematics.svg)

This is a Sphinx extension to automatically document [Schematics](https://schematics.readthedocs.io/) models.

## How to use it

In your Sphinx configuration you will need to list `autoschematics` as an extension:

```python
extensions = ["autoschematics", "sphinx.ext.autodoc"]
```

This will provide a new `automodel` directive that you can provide the full path of a model to:

```
.. automodel:: myproject.models.MyModel
```

The extension will inspect your model and generate documentation from the docstring and the different fields on the model.


## Example

Given the following model:

```python
from schematics import types
from schematics.models import Model
from schematics.types import compound


class MyModel(Model):
    """MyModel defines the structure of data when interacting with SomeService

    Just like in Sphinx .rst files you can use restructured text directives in the
    docstring to provide rich content in the generated docs.

    .. code-block:: yaml

        foo: Foo
        bar:
          - bar1
          - bar2
    """

    foo = types.StringType(
        required=True,
        metadata=dict(
            custom_value=True
        )
    )

    bar = compound.ListType(types.StringType, default=list)
```

Would produce documentation like:

#### models.MyModel

MyModel defines the structure of data when interacting with SomeService 

Just like in Sphinx .rst files you can use restructured text directives in the
docstring to provide rich content in the generated docs.

```yaml
foo: Foo
bar:
  - bar1
  - bar2
```

<dl class="attribute">
<dt id="models.ExampleModel.foo">
<code class="sig-name descname">foo</code><em class="property"> StringType()</em></dt>
<dd><div class="line-block">
<div class="line"><strong>Required</strong>: True</div>
<div class="line"><strong>Default</strong>: Undefined</div>
<div class="line"><strong>Custom value</strong>: True</div>
</div>
</dd></dl>

<dl class="attribute">
<dt id="models.ExampleModel.bar">
<code class="sig-name descname">bar</code><em class="property"> ListType(StringType())</em></dt>
<dd><div class="line-block">
<div class="line"><strong>Required</strong>: False</div>
<div class="line"><strong>Default</strong>: Undefined</div>
</div>
</dd></dl>


