docformatter

文档格式化程序

代码
文档字符串
GitHub
皮皮

格式化文档字符串以遵循 PEP 257。

特征

docformatter自动格式化文档字符串以遵循 PEP 257 约定的子集。以下是引用自 PEP 257 的相关内容。

• 为了保持一致性，请始终在文档字符串周围使用三重双引号。
• 即使字符串适合一行，也会使用三引号。
• 多行文档字符串由一个摘要行组成，就像单行文档字符串一样，后跟一个空行，然后是更详细的描述。
• 除非整个文档字符串适合一行，否则请将结束引号单独放在一行上。

docformatter还处理一些 PEP 8 约定。

• 不要编写依赖于重要尾随空格的字符串文字。这种尾随空白在视觉上是无法区分的，一些编辑器（或者最近的reindent.py）会修剪它们。

当传递--black选项时， docformatter格式化与black兼容的文档字符串。

docformatter格式化使用 Epytext 或 Sphinx 样式的字段列表。

请参阅阅读文档中的完整文档，特别是要求部分，以获取 PEP 257 和其他要求的更详细讨论。

安装

来自点：

 $ pip install --升级 docformatter

或者，如果您想使用 pyproject.toml 来配置 docformatter 并且您使用的是 Python < 3.11：

 $ pip install --upgrade docformatter[tomli]

对于 Python >=3.11，使用标准库中的tomllib 。

或者，如果您想使用候选版本（或任何其他标签）：

 $ pip install git+https://github.com/PyCQA/docformatter.git@

其中 是您要安装的候选版本标签。候选版本标签的格式为 v1.6.0-rc1 候选版本也将作为 Github 版本提供。

例子

运行后：

 $ docformatter --就地 example.py

这段代码

 """   Here are some examples.

    This module docstring should be dedented."""


def launch_rocket ():
    """Launch
the
rocket. Go colonize space."""


def factorial ( x ):
    '''

    Return x factorial.

    This uses math.factorial.

    '''
    import math
    return math . factorial ( x )


def print_factorial ( x ):
    """Print x factorial"""
    print ( factorial ( x ))


def main ():
    """Main
    function"""
    print_factorial ( 5 )
    if factorial ( 10 ):
        launch_rocket ()

被格式化成这样

 """Here are some examples.

This module docstring should be dedented.
"""


def launch_rocket ():
    """Launch the rocket.

    Go colonize space.
    """


def factorial ( x ):
    """Return x factorial.

    This uses math.factorial.
    """
    import math
    return math . factorial ( x )


def print_factorial ( x ):
    """Print x factorial."""
    print ( factorial ( x ))


def main ():
    """Main function."""
    print_factorial ( 5 )
    if factorial ( 10 ):
        launch_rocket ()

营销

你使用docformatter吗？您使用什么风格的文档字符串？在项目的自述文件中添加一些徽章并让每个人都知道。

 .. 图片:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
    ：目标：https://github.com/PyCQA/docformatter

.. 图片:: https://img.shields.io/badge/%20style-sphinx-0a507a.svg
    ：目标：https://www.sphinx-doc.org/en/master/usage/index.html

.. 图片:: https://img.shields.io/badge/%20style-numpy-459db9.svg
    ：目标：https://numpydoc.readthedocs.io/en/latest/format.html

.. 图片:: https://img.shields.io/badge/%20style-google-3666d6.svg
    ：目标：https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings

问题

可以在 GitHub 页面上报告错误和补丁。