档案：一种编写python代码文档的新方法

archives是一种新风格的 python 代码文档，也是文档本身的 linter。它可以帮助您确保您的类和函数中的文档字符串保持最新，并且它们充分解释了它们的目的、参数和返回值。

特征

• 用于文档字符串的 linter（正在进行中，但可用！）
• （即将推出）文档生成器

用法

安装

pip install archives

运行 Linter

# run archives (on itself!)
archives archives/

# archives.py:846:0: F104 function 'path_empty' missing @ret tag
#
# Impossible! Perhaps your archives are incomplete?
# 1 issues found.

# list tags!
archives --list-tag

# @arg    describe an argument of a function
# @author denote the author of a module/class/function
# @cc     denote the complexity of a function
# @desc   describe a module/class/function
# @link   add a link to the generated documentation
# @nodoc  disable this module/class/function in the documentation
# @nolint disable archives linting in this module/class/function
# @note   add a note to a module/class/function
# @ret    describe the return value of a function
# @todo   tag something as a todo
# @warn   add a warning to a module/class/function

# list rules!
archives --list-rules


# disable rules!
archives --disable M100 .

# different formats for output! defaults to flake8
archives --format pylint archives.py

测试

可以使用 tox 运行测试！

# run tests
tox

# only one version of python
tox -e py36

去做

• 更多规则
• 更好的多检查规则系统
• 更多输出格式
• 可能在 desc 中进行拼写检查？
• 文档生成器
• 测试