docformatter

формат документа

Код
Строки документации
GitHub
ПиПи

Форматирует строки документации в соответствии с PEP 257.

Функции

docformatter автоматически форматирует строки документации в соответствии с подмножеством соглашений PEP 257. Ниже приведены соответствующие пункты, цитируемые из PEP 257.

• Для единообразия всегда используйте тройные двойные кавычки вокруг строк документации.
• Тройные кавычки используются, даже если строка умещается на одной строке.
• Многострочные строки документации состоят из строки резюме, как и однострочная строка документации, за которой следует пустая строка, за которой следует более подробное описание.
• Если вся строка документации не умещается в одной строке, размещайте закрывающие кавычки в отдельной строке.

docformatter также поддерживает некоторые соглашения PEP 8.

• Не пишите строковые литералы, которые полагаются на значительные конечные пробелы. Такие конечные пробелы визуально неразличимы, и некоторые редакторы (или, с недавних пор, reindent.py) их обрезают.

docformatter форматирует строки документации, совместимые с black если указан параметр --black .

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 ()

Маркетинг

Используете ли вы docformatter ? Какие строки документации по стилю вы используете? Добавьте несколько значков в 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.