Cookiecutter Django 项目文档体系指南用 Sphinx 构建、实时预览并从 Docstring 自动生成 API 文档【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django本指南面向使用 Cookiecutter Django 脚手架生成 Django 项目的开发者讲解生成项目中内置的 Sphinx 文档体系如何在本地或 Docker 容器中构建并实时预览文档以及如何借助sphinx-apidoc与 Napoleon 扩展把源码中的 Numpy/Google 风格 Docstring 自动编译为可检索的 API 文档。读完本文你将掌握生成项目文档的标准工作流并能根据use_docker选项选择正确的构建命令。文档从哪来生成项目内置的 docs 目录Cookiecutter Django 在生成项目时会在项目根目录下创建一套完整的docs目录对应模板位置为 {{cookiecutter.project_slug}}/docs其中预置了Makefile与make.bat分别是 Unix/Linux/macOS 与 Windows 下的文档构建入口conf.pySphinx 构建配置扩展、项目信息、HTML 主题等index.rst文档首页通过toctree指令聚合howto与users等章节howto.rst即本文主题所在的如何写文档指南users.rst一个使用automodule指令从源码自动生成用户模型文档的现成示例pycharm/configuration.rst仅在生成时选择 PyCharm 编辑器才会包含的编辑器配置文档。这套文档体系使用Sphinx作为构建工具见 howto.rst全部文档源文件以 reStructuredText.rst格式编写存放在 docs 目录中。生成项目后你可以直接在这些.rst文件中书写项目文档而不是把文档散落在 README 或代码注释里。构建并实时预览文档关键前提use_docker 选项决定命令形态生成项目时cookiecutter.json 中的use_docker选项决定了文档构建方式选择n默认值使用本机uv工具链直接构建选择y使用 Docker Compose 在容器中构建。两种方式的结果一致只是运行环境不同具体命令见下。方式一非 Docker 环境use_docker n在生成项目的docs目录内执行uv run make livehtml该命令的核心是调用 Sphinx 的自动重建工具sphinx-autobuild其实际实现定义在 docs/Makefilelivehtml: sphinx-autobuild -b html --open-browser --port 9000 --watch $(APP) -c . $(SOURCEDIR) $(BUILDDIR)/html其中--port 9000文档服务监听 9000 端口浏览器访问http://localhost:9000即可查看--open-browser启动后自动打开默认浏览器--watch $(APP)监听源码目录的变化APP指向生成的应用目录非 Docker 环境下为../{{cookiecutter.project_slug}}意味着应用源码改动也会触发文档重构建-c .使用 docs 目录下的conf.py作为构建配置。Makefile 中SOURCEDIR .即文档源目录就是docs目录本身Windows 下的 make.bat 是另一套等效实现。因此任何对 docs 目录内.rst文件的修改都会立即被监听并自动重载浏览器无需手动刷新即可看到最新内容非常适合边写文档边校对。方式二Docker 环境use_docker y在项目根目录执行docker compose -f docker-compose.docs.yml up该命令使用的服务定义见 docker-compose.docs.yml镜像由 compose/local/docs/Dockerfile 构建基于ghcr.io/astral-sh/uv:python3.14-bookworm-slim内部预装make、libpq-dev、gettext等依赖并通过uv sync同步项目依赖容器工作目录为/docs启动脚本 compose/local/docs/start 实际执行的仍是make livehtml通过 volumes 将./docs、./config、./{{cookiecutter.project_slug}}挂载进容器宿主机上的文档与源码改动会被容器内同步感知并触发重载端口映射为9000:9000同样通过http://localhost:9000访问容器内livehtml目标额外带--host 0.0.0.0见 Makefile方便在容器或远程环境中访问。从 Docstring 自动生成 API 文档除了手写.rst文件文档体系还内置了Docstring 转文档的自动化链路以源码中的函数签名与 Docstring 为原料自动产出 API 文档章节。支持的 Docstring 风格项目使用 Sphinx 的Napoleon扩展解析 Docstring这意味着你可以在代码里使用Numpy 风格或 Google 风格的 Docstring构建时都会被正确识别并渲染。以 Numpy 风格为例def activate_user(user_id: int) - bool: Activate a user account. Parameters ---------- user_id : int The database id of the user to activate. Returns ------- bool True if the user was activated, False otherwise. ...Napoleon 扩展会在 conf.py 中被启用与sphinx.ext.autodoc一起构成文档自动生成的核心extensions [ sphinx.ext.autodoc, sphinx.ext.napoleon, ]其中autodoc负责从 Python 模块导入并提取 Docstringnapoleon负责把 Numpy/Google 风格的 Docstring 转换成 Sphinx 能渲染的格式。如何在 .rst 中引用源码文档自动生成的文档通过automodule/autoclass/autofunction等指令嵌入到.rst文件中。生成项目自带的 users.rst 就是现成范例.. automodule:: {{cookiecutter.project_slug}}.users.models :members: :noindex:这条指令会把users.models模块中所有公开类与方法的签名和 Docstring 渲染成文档:members:表示同时列出模块成员:noindex:表示不额外生成索引条目。而index.rst通过toctree把howto、users等章节聚合进文档站点形成完整的导航结构见 docs/index.rst。一次性编译全部 Docstringmake apidocs如果想为整个 Django 应用批量生成 API 文档源文件在docs目录内执行uv run make apidocs该目标在 Makefile 中的实现为apidocs: sphinx-apidoc -o $(SOURCEDIR)/api $(APP)即调用 Sphinx 自带的sphinx-apidoc工具扫描APP生成的应用源码目录下所有模块把每个模块的签名与 Docstring 编译为 reStructuredText 文件输出到docs/api/目录。生成后再把这些.rst文件纳入toctree即可与手写文档无缝整合。Docker 环境下的等效命令若使用 Docker 构建文档use_docker y可以用如下命令在已构建的docs镜像中执行apidocs目标docker run --rm docs make apidocs--rm保证命令执行完毕后容器自动清理不影响宿主机环境。构建配置的底层细节conf.py 做了什么conf.py 是 Sphinx 构建的核心配置理解它能帮助你排查构建问题Django 环境初始化conf.py会在构建时执行django.setup()并把DATABASE_URL指向sqlite:///readthedocs.db、DJANGO_SETTINGS_MODULE设为config.settings.local。这保证autodoc能顺利导入 Django 模型与视图导入即触发 Django 配置加载而无需真实数据库路径注入sys.path会按环境插入/appDocker或上级目录本机确保应用模块可被导入在 ReadTheDocs 等 CI 环境READTHEDOCSTrue下走独立的路径与USE_DOCKERno分支主题与排除项HTML 主题为alabaster构建时排除_build、.DS_Store等目录避免产物污染源目录。Windows 用户make.bat在 Windows 环境下make命令不可用生成项目提供了等价的 make.batmake.bat livehtml make.bat apidocs其livehtml与apidocs目标分别调用sphinx-autobuild与sphinx-apidoc参数含义与 Makefile 一致端口同样为 9000APP指向..\{{cookiecutter.project_slug}}。如果sphinx-build未安装批处理会给出明确提示。推荐工作流小结在项目docs目录下手写.rst文档如index.rst、功能说明章节并通过toctree组织导航为应用代码补充 Numpy/Google 风格 Docstring执行uv run make apidocs或 Docker 下docker run --rm docs make apidocs批量生成docs/api/下的 API 文档执行uv run make livehtml或docker compose -f docker-compose.docs.yml up启动 9000 端口的实时预览边写边校验渲染效果将全部.rst源文件与代码一起提交到版本库让文档与代码同步演进。这套手写指南 Docstring 自动生成 实时预览的组合正是 Cookiecutter Django 生成项目文档体系的完整形态既保证 API 文档与源码永远一致又允许开发者用自然的 Docstring 风格书写无需额外维护重复的 API 文档。【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cookiecutter Django 项目文档体系指南：用 Sphinx 构建、实时预览并从 Docstring 自动生成 API 文档
Cookiecutter Django 项目文档体系指南用 Sphinx 构建、实时预览并从 Docstring 自动生成 API 文档【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django本指南面向使用 Cookiecutter Django 脚手架生成 Django 项目的开发者讲解生成项目中内置的 Sphinx 文档体系如何在本地或 Docker 容器中构建并实时预览文档以及如何借助sphinx-apidoc与 Napoleon 扩展把源码中的 Numpy/Google 风格 Docstring 自动编译为可检索的 API 文档。读完本文你将掌握生成项目文档的标准工作流并能根据use_docker选项选择正确的构建命令。文档从哪来生成项目内置的 docs 目录Cookiecutter Django 在生成项目时会在项目根目录下创建一套完整的docs目录对应模板位置为 {{cookiecutter.project_slug}}/docs其中预置了Makefile与make.bat分别是 Unix/Linux/macOS 与 Windows 下的文档构建入口conf.pySphinx 构建配置扩展、项目信息、HTML 主题等index.rst文档首页通过toctree指令聚合howto与users等章节howto.rst即本文主题所在的如何写文档指南users.rst一个使用automodule指令从源码自动生成用户模型文档的现成示例pycharm/configuration.rst仅在生成时选择 PyCharm 编辑器才会包含的编辑器配置文档。这套文档体系使用Sphinx作为构建工具见 howto.rst全部文档源文件以 reStructuredText.rst格式编写存放在 docs 目录中。生成项目后你可以直接在这些.rst文件中书写项目文档而不是把文档散落在 README 或代码注释里。构建并实时预览文档关键前提use_docker 选项决定命令形态生成项目时cookiecutter.json 中的use_docker选项决定了文档构建方式选择n默认值使用本机uv工具链直接构建选择y使用 Docker Compose 在容器中构建。两种方式的结果一致只是运行环境不同具体命令见下。方式一非 Docker 环境use_docker n在生成项目的docs目录内执行uv run make livehtml该命令的核心是调用 Sphinx 的自动重建工具sphinx-autobuild其实际实现定义在 docs/Makefilelivehtml: sphinx-autobuild -b html --open-browser --port 9000 --watch $(APP) -c . $(SOURCEDIR) $(BUILDDIR)/html其中--port 9000文档服务监听 9000 端口浏览器访问http://localhost:9000即可查看--open-browser启动后自动打开默认浏览器--watch $(APP)监听源码目录的变化APP指向生成的应用目录非 Docker 环境下为../{{cookiecutter.project_slug}}意味着应用源码改动也会触发文档重构建-c .使用 docs 目录下的conf.py作为构建配置。Makefile 中SOURCEDIR .即文档源目录就是docs目录本身Windows 下的 make.bat 是另一套等效实现。因此任何对 docs 目录内.rst文件的修改都会立即被监听并自动重载浏览器无需手动刷新即可看到最新内容非常适合边写文档边校对。方式二Docker 环境use_docker y在项目根目录执行docker compose -f docker-compose.docs.yml up该命令使用的服务定义见 docker-compose.docs.yml镜像由 compose/local/docs/Dockerfile 构建基于ghcr.io/astral-sh/uv:python3.14-bookworm-slim内部预装make、libpq-dev、gettext等依赖并通过uv sync同步项目依赖容器工作目录为/docs启动脚本 compose/local/docs/start 实际执行的仍是make livehtml通过 volumes 将./docs、./config、./{{cookiecutter.project_slug}}挂载进容器宿主机上的文档与源码改动会被容器内同步感知并触发重载端口映射为9000:9000同样通过http://localhost:9000访问容器内livehtml目标额外带--host 0.0.0.0见 Makefile方便在容器或远程环境中访问。从 Docstring 自动生成 API 文档除了手写.rst文件文档体系还内置了Docstring 转文档的自动化链路以源码中的函数签名与 Docstring 为原料自动产出 API 文档章节。支持的 Docstring 风格项目使用 Sphinx 的Napoleon扩展解析 Docstring这意味着你可以在代码里使用Numpy 风格或 Google 风格的 Docstring构建时都会被正确识别并渲染。以 Numpy 风格为例def activate_user(user_id: int) - bool: Activate a user account. Parameters ---------- user_id : int The database id of the user to activate. Returns ------- bool True if the user was activated, False otherwise. ...Napoleon 扩展会在 conf.py 中被启用与sphinx.ext.autodoc一起构成文档自动生成的核心extensions [ sphinx.ext.autodoc, sphinx.ext.napoleon, ]其中autodoc负责从 Python 模块导入并提取 Docstringnapoleon负责把 Numpy/Google 风格的 Docstring 转换成 Sphinx 能渲染的格式。如何在 .rst 中引用源码文档自动生成的文档通过automodule/autoclass/autofunction等指令嵌入到.rst文件中。生成项目自带的 users.rst 就是现成范例.. automodule:: {{cookiecutter.project_slug}}.users.models :members: :noindex:这条指令会把users.models模块中所有公开类与方法的签名和 Docstring 渲染成文档:members:表示同时列出模块成员:noindex:表示不额外生成索引条目。而index.rst通过toctree把howto、users等章节聚合进文档站点形成完整的导航结构见 docs/index.rst。一次性编译全部 Docstringmake apidocs如果想为整个 Django 应用批量生成 API 文档源文件在docs目录内执行uv run make apidocs该目标在 Makefile 中的实现为apidocs: sphinx-apidoc -o $(SOURCEDIR)/api $(APP)即调用 Sphinx 自带的sphinx-apidoc工具扫描APP生成的应用源码目录下所有模块把每个模块的签名与 Docstring 编译为 reStructuredText 文件输出到docs/api/目录。生成后再把这些.rst文件纳入toctree即可与手写文档无缝整合。Docker 环境下的等效命令若使用 Docker 构建文档use_docker y可以用如下命令在已构建的docs镜像中执行apidocs目标docker run --rm docs make apidocs--rm保证命令执行完毕后容器自动清理不影响宿主机环境。构建配置的底层细节conf.py 做了什么conf.py 是 Sphinx 构建的核心配置理解它能帮助你排查构建问题Django 环境初始化conf.py会在构建时执行django.setup()并把DATABASE_URL指向sqlite:///readthedocs.db、DJANGO_SETTINGS_MODULE设为config.settings.local。这保证autodoc能顺利导入 Django 模型与视图导入即触发 Django 配置加载而无需真实数据库路径注入sys.path会按环境插入/appDocker或上级目录本机确保应用模块可被导入在 ReadTheDocs 等 CI 环境READTHEDOCSTrue下走独立的路径与USE_DOCKERno分支主题与排除项HTML 主题为alabaster构建时排除_build、.DS_Store等目录避免产物污染源目录。Windows 用户make.bat在 Windows 环境下make命令不可用生成项目提供了等价的 make.batmake.bat livehtml make.bat apidocs其livehtml与apidocs目标分别调用sphinx-autobuild与sphinx-apidoc参数含义与 Makefile 一致端口同样为 9000APP指向..\{{cookiecutter.project_slug}}。如果sphinx-build未安装批处理会给出明确提示。推荐工作流小结在项目docs目录下手写.rst文档如index.rst、功能说明章节并通过toctree组织导航为应用代码补充 Numpy/Google 风格 Docstring执行uv run make apidocs或 Docker 下docker run --rm docs make apidocs批量生成docs/api/下的 API 文档执行uv run make livehtml或docker compose -f docker-compose.docs.yml up启动 9000 端口的实时预览边写边校验渲染效果将全部.rst源文件与代码一起提交到版本库让文档与代码同步演进。这套手写指南 Docstring 自动生成 实时预览的组合正是 Cookiecutter Django 生成项目文档体系的完整形态既保证 API 文档与源码永远一致又允许开发者用自然的 Docstring 风格书写无需额外维护重复的 API 文档。【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考