sphinx-autoschematics

这是一个用于自动文档化 Schematics 模型的 Sphinx 扩展。

如何使用它

在您的 Sphinx 配置中，您需要将 autoschematics 列为扩展

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

这将为您提供一个新的 automodel 指令，您可以为模型提供完整路径

.. automodel:: myproject.models.MyModel

扩展将检查您的模型，并根据模型上的 docstring 和不同字段生成文档

示例

假设以下模型

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)

将生成以下文档

models.MyModel

MyModel 定义了与 SomeService 交互时的数据结构

就像在 Sphinx .rst 文件中一样，您可以在 docstring 中使用 restructured text 指令，以在生成的文档中提供丰富内容

foo: Foo
bar:
  - bar1
  - bar2

foo StringType()

必需: True

默认值: Undefined

自定义值: True

bar ListType(StringType())

必需: False

默认值: Undefined