如果要编写Python代码的话，我一定会想使用两种绝对必备的文档生成工具

2 年 ago

新, 韵

2 minutes

我开始全力学习Python和Django已经有三个月了，从我的角度来看，我要介绍两个我认为非常实用的文档生成工具！下面按照每个工具在Django中应用的方法来进行说明。

如果您能参考django的适用示例，即使进行搜索也会找到排名靠前的内容，那将是非常令人愉快的。

使用 Sphinx 编写 docstring 文档

Sphinx是一种工具，能够轻松创建智能美观的文档。它由Georg Brandl开发，并在BSD许可证下发布。

这个工具最初是为Python文档而创建的，现在被广泛应用于各种语言的项目中，用于简化文档创建。(来自官方网站)

我第一次听说这个项目是通过“Read the docs”这个为开源社区提供文档托管服务的平台。顺带一提，听说这个服务也是用Django构建的。

jupyter notebookの例

只需要一种选择：
在Sphinx中，您需要使用一种被称为reStructuredText的标记语言，但是您可以使用sphinx-apidoc命令自动生成rst源代码。
将源文本转换为rst要使用docstring。据sphinx配置文件conf.py中的sphinx.ext.autodoc所述，它能够在原始目录下查找docstring。换句话说，
python docstring -> rst -> html
Sphinx会负责全部转换工作！非常感谢！

制作步骤

我们立即开始创建Django项目的文档吧！

在开始python项目之前，需要提前编写docstring。
如果你对docstring是什么有疑问的话，推荐阅读这篇文章->Google docstring 入门。

在终端上执行以下命令。

# ライブラリとテーマインストール
pip install sphinx sphinx-rtd-theme
# ドキュメント出力先作成
mkdir docs
# django project rootを指定してrst作成
sphinx-apidoc -fF -o ./docs ./path/to/django_project_root
# change directory
cd docs
# conf.pyの調整(内容別途書いています！)
vi conf.py
# html作成
make html

conf.py

请只记录附加部分。
请参考# — hogehoge ——–来确定附加位置。


# -- Path setup --------------------------------------------------------------

# django projectへのパスとsettingsを指定
import os
import sys
sys.path.insert(0, os.path.abspath('path/to/django_project_root'))
import django
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
django.setup()

# -- General configuration ---------------------------------------------------

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.napoleon', # google, numpy styleのdocstring対応
]

language = 'ja' # あいあむじゃぱにーず

# -- Options for HTML output -------------------------------------------------

html_theme = 'sphinx_rtd_theme' # Read the Docsの見た目指定

虽然仅仅是自动生成而已，但完成度相当高！如果想整理自动生成的 rst，我认为这篇文章会非常有参考价值。→ 学习 Sphinx。
因为我编写的 rst 链接与 Django 项目使用的目录名冲突，所以我进行了一部分 rst 的修改。（・_・）

使用覆盖率生成覆盖报告。

下一步是生成测试覆盖率报告！完成图像位于这里。
我们会使用两个工具来完成，分别是pytest和coverage！

pytest 是一款成熟且功能完备的 Python 测试工具，可帮助编写更好的程序。
使用 pytest 框架，可以轻松编写小规模的测试，并可扩展以支持复杂的应用程序和库功能测试。(by 官方)

pytest是Python的一个测试框架之一。尽管Python有一个名为unittest的标准测试框架，但个人更倾向于pytest，因为它的比较操作符更加直观易懂。

Coverage.py是一种用于测量Python程序代码覆盖率的工具。它监视程序并记录代码的执行情况，通过分析源代码，可以确定哪些代码有可能被执行但实际未执行。
代码覆盖度的测量通常用于评估测试的有效性。它可以显示哪些代码部分被测试执行过, 哪些代码部分未被执行。(by 公式)

这对于确认已测试代码的覆盖率非常有帮助。虽然达到100％会让人感到满意，但还有其他需要确认的方面，所以请注意。

Coverage功能之一是具备报告HTML输出功能。

ドキュメント作成の手間を削減できる

这是个一举两得的方法！请务必尝试一下！

制作流程

那么，让我们来进行Django项目中的pytest和coverage的设置以及生成报告的输出！

在终端上执行以下命令。

# ライブラリをインストール
pip install pytest-django coverage
# change directory(django projectのディレクトリ)
cd django_project_path
# pytest.iniの調整(内容別途書いています！)
vi pytest.ini
# p.coveragercの調整(内容別途書いています！)
vi .coveragerc
# coverageの取得
coverage run -m pytest
# coverage reportの確認
coverage report -m
# coverage htmlの出力
coverage html

pytest.ini

这次我们进行了最基本的设置。官方的pytest-django也很简洁易懂，建议您去检查一下。

[pytest]
addopts = --ds=config.settings # django settingsを指定
python_files = tests.py test_*.py # テストコードを指定

.coveragerc

这个文件定义了coverage命令的run、report、html选项。这份官方coverage的选项说明也很简单易懂。除了可以输出html，还可以输出xml和json。

[run]
source=. # django project rootを指定
omit= */migrations/*　# 対象外にしたいファイル、ディレクトリを記載
      */tests/*
      */htmlcov/*
[report]
omit= */migrations/*
      */tests/*
[html]
directory = htmlcov # htmlcovというディレクトリにhtmlを出力します

如果需要获取html覆盖率，执行pip install django-coverage-plugin，并添加以下内容。

[run]
plugins =
    django_coverage_plugin

参考：Django笔记(26)：使用coverage.py进行覆盖率测量

这里也可以通过简单的操作自动生成清晰易读的文档！如果使用命令行操作，你可以使用coverage report -m命令来查看未覆盖的代码行号，也可以使用pytest -v命令来显示详细的测试信息，非常直观易懂。

最后

如果能够使用时，可以通过简化文档创建过程，提高工作效率。无论是使用django还是其他工具都可以，建议尝试一下。如果您知道其他推荐的自动文档生成工具，请留言告知，不胜感激。

感谢您的阅读。