生成文档¶

可以使用TOX本身生成项目文档。此路径的优势在于，现在生成文档可以是CI的一部分，只要在生成文档时任何验证/检查/操作失败，您就会在tox中捕获它。

Shpinx¶

不需要使用神秘的make文件来生成Shinx文档。可以使用tox来确保所有正确的依赖项在虚拟环境中都可用，甚至可以指定执行构建所需的python版本。例如，如果sphinx文件结构位于 doc 文件夹下面的配置将在以下位置生成文档 {{toxworkdir}}/docs_out 并打印出指向生成的文档的链接：

[testenv:docs]
description = invoke sphinx-build to build the HTML docs
basepython = python3.7
deps = sphinx >= 1.7.5, < 2
commands = sphinx-build -d "{toxworkdir}/docs_doctree" doc "{toxworkdir}/docs_out" --color -W -bhtml {posargs}
           python -c 'import pathlib; print("documentation available under file://\{0\}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))'

注意，这里我们说我们还需要python3.7，允许我们在狮身人面像中使用f字符串 conf.py 。现在可以指定单独的测试环境来验证链接是否正确。

mkdocs¶

定义一个环境来编写/生成文档，定义另一个环境来部署文档。使用配置替换逻辑可避免多次定义依赖项：

[testenv:docs]
description = Run a development server for working on documentation
basepython = python3.7
deps = mkdocs >= 1.7.5, < 2
       mkdocs-material
commands = mkdocs build --clean
           python -c 'print("###### Starting local server. Press Control+C to stop server ######")'
           mkdocs serve -a localhost:8080

[testenv:docs-deploy]
description = built fresh docs and deploy them
deps = {[testenv:docs]deps}
basepython = {[testenv:docs]basepython}
commands = mkdocs gh-deploy --clean

Fork me on GitHub