sphinxcontrib-django 2.5

功能

改进 Sphinx 的 autodoc 对 Django 类的输出

• 列出所有模型和表单字段作为类参数

• 改进模型字段表示

• 将相关和反向相关字段链接到引用类

• 从类中隐藏不相关的运行时信息，如 declared_fieldsets、fieldsets 和 Meta

• 添加关于自动生成方法的信息

• 修复 intersphinx 到 Django 模块的映射

• 自定义文本角色以交叉引用 Django（《:setting:》、《:templatetag:》、《:templatefilter:》、《:fieldlookup:》）和 Sphinx（《:event:》、《:confval:》）的文档

安装

通过 pip 安装该软件包

pip install sphinxcontrib-django

配置

将以下内容添加到您的 Sphinx 配置文件 conf.py

# Add source directory to sys.path
sys.path.insert(0, os.path.abspath("../src"))

# Add sphinxcontrib_django to installed extensions
extensions = [
    "sphinxcontrib_django",
]

# Configure the path to the Django settings module
django_settings = "myapp.settings"

可选地，您可以使用以下方式在模型的 docstrings 中包含模型表名

# Include the database table names of Django models
django_show_db_tables = True                # Boolean, default: False
# Add abstract database tables names (only takes effect if django_show_db_tables is True)
django_show_db_tables_abstract = True       # Boolean, default: False

可选地，您可以使用它们扩展模型字段中显示的选择数量

# Integer amount of model field choices to show, default 10
django_choices_to_show = 10

高级使用

如果您想运行依赖于 Django 的自定义代码，例如在文档构建期间 monkeypatch 您的应用程序，您可能会遇到 ImproperlyConfigured 异常

请求设置 INSTALLED_APPS，但设置尚未配置。您必须定义环境变量 DJANGO_SETTINGS_MODULE 或在访问设置之前调用 settings.configure()。

因此，此 Sphinx 扩展在 django.setup() 完成后发出事件 django-configured，因此您可以在 conf.py 中以下方式运行您的代码

def patch_django(app):
    """
    Your custom code here
    """

def setup(app):
    app.connect("django-configured", patch_django)

贡献

欢迎提交拉取请求！

您可以使用额外的 dev、test、doc 和 optional 安装所有开发设置的要求

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev,test,doc,optional]
pre-commit install

使用以下内容运行测试和生成覆盖率报告

coverage run
coverage html

使用以下内容构建文档

cd docs
make html

文档会自动部署到 Read the Docs。