docformatter

ドキュメントフォーマッタ

コード
ドキュメントストリング
GitHub
ピピ

PEP 257 に従うように docstring をフォーマットします。

特徴

docformatter 、PEP 257 規則のサブセットに従って docstring を自動的にフォーマットします。以下は PEP 257 から引用した関連項目です。

• 一貫性を保つために、常に docstring を三重二重引用符で囲んでください。
• 文字列が 1 行に収まる場合でも、三重引用符が使用されます。
• 複数行の docstring は、1 行の docstring と同様に概要行と、その後に続く空行、さらに詳しい説明で構成されます。
• docstring 全体が 1 行に収まらない場合は、終了引用符を単独で 1 行に配置します。

docformatter PEP 8 規則の一部も処理します。

• 重要な末尾の空白に依存する文字列リテラルを記述しないでください。このような末尾の空白は視覚的には区別できないため、一部のエディタ (最近では reindent.py) はそれらをトリミングします。

docformatterは、 --black black オプションが渡された場合に、 blackと互換性のある docstring をフォーマットします。

docformatter Epytext または Sphinx スタイルを使用するフィールド リストをフォーマットします。

read-the-docs で完全なドキュメントを参照してください。特に、PEP 257 およびその他の要件の詳細については、要件セクションを参照してください。

インストール

ピップより:

 $ pip install --upgrade 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 --in-place 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 ()

マーケティング

ドキュメントフォーマッタを使用していますか?どのような形式の docstring を使用しますか?プロジェクトのREADMEにいくつかのバッジを追加して、全員に知らせてください。

 .. 画像:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
    :target: https://github.com/PyCQA/docformatter

.. 画像:: https://img.shields.io/badge/%20style-sphinx-0a507a.svg
    :target: https://www.sphinx-doc.org/en/master/usage/index.html

.. 画像:: https://img.shields.io/badge/%20style-numpy-459db9.svg
    :target: https://numpydoc.readthedocs.io/en/latest/format.html

.. 画像:: https://img.shields.io/badge/%20style-google-3666d6.svg
    :target: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings

問題

バグとパッチは GitHub ページで報告できます。