存档：以新的方式编写python代码文档

存档 是一种新的python代码文档风格，同时也是文档本身的lint工具。它可以帮助您确保您的类和函数中的docstrings保持最新，并且能够充分解释其目的、参数和返回值。

功能

• docstrings的lint工具（正在开发中，但可用！）
• （即将推出）文档生成器

使用方法

安装

pip install archives

运行lint工具

# 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

待办事项

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