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 頁面上報告錯誤和補丁。