Документирование кода Python

Оглавление

Почему документирование кода так важно
Комментирование против документирования кода
- Основы комментирования кода
- Комментирование кода с помощью подсказки типов (Python 3.5+)
Документирование базы кода Python с помощью докстрингов
Документирование ваших проектов на Python
"С чего начать?"

Добро пожаловать в ваше полное руководство по документированию кода на Python. Неважно, документируете ли вы небольшой скрипт или большой проект, являетесь ли вы новичком или опытным Pythonистом, в этом руководстве вы найдете все, что вам нужно знать.

Мы разбили этот учебник на четыре основных раздела:

Почему документирование кода так важно: Введение в документирование и его важность
Комментирование и документирование кода: Обзор основных различий между комментированием и документированием, а также подходящие моменты и способы использования комментирования
Documenting Your Python Code Base Using Docstrings: Глубокое погружение в документацию для классов, методов классов, функций, модулей, пакетов и скриптов, а также что должно быть в каждой из них
Документирование ваших Python-проектов: необходимые элементы и что они должны содержать для ваших Python-проектов

Не стесняйтесь прочитать это руководство от начала до конца или перейти к интересующему вас разделу. Он был разработан так, чтобы работать в обоих направлениях.

Почему документирование кода так важно

Надеемся, если вы читаете это руководство, вы уже знаете, как важно документировать свой код. Но если нет, то позвольте мне процитировать кое-что, что Гвидо упомянул мне на недавнем PyCon:

"Код чаще читают, чем пишут".

- Гвидо ван Россум

Когда вы пишете код, вы пишете его для двух основных аудиторий: ваших пользователей и ваших разработчиков (включая вас самих). Обе аудитории одинаково важны. Если вы похожи на меня, то наверняка открывали старые кодовые базы и удивлялись: "О чем я только думал?". Если у вас возникают проблемы с чтением собственного кода, представьте, что испытывают ваши пользователи или другие разработчики, когда пытаются использовать или создать ваш код.

И наоборот, я уверен, что вы сталкивались с ситуацией, когда хотели сделать что-то на Python и нашли, как кажется, отличную библиотеку, которая может выполнить эту работу. Однако когда вы начинаете использовать библиотеку, вы ищете примеры, статьи или даже официальную документацию о том, как сделать что-то конкретное, и не можете сразу найти решение.

После поисков вы обнаруживаете, что документация отсутствует или, что еще хуже, отсутствует полностью. Это разочаровывающее чувство, которое отталкивает вас от использования библиотеки, каким бы замечательным или эффективным ни был код. Даниэле Прочида лучше всего подытожил эту ситуацию:

"Неважно, насколько хорошо ваше программное обеспечение, потому что если документация
недостаточно хороша, люди не будут его использовать".
- Даниэле Прочида

В этом руководстве вы с нуля узнаете, как правильно документировать код на Python - от самых маленьких скриптов до самых больших Python-проектов - чтобы ваши пользователи никогда не испытывали разочарования при использовании или внесении вклада в ваш проект.

Комментирование против документирования кода

Прежде чем мы перейдем к тому, как документировать код на Python, нам нужно отличить документирование от комментирования.

В целом, комментирование - это описание вашего кода для разработчиков. Предполагаемая основная аудитория - это сопровождающие и разработчики кода Python. В сочетании с хорошо написанным кодом комментарии помогают читателю лучше понять ваш код, его назначение и дизайн:

"Код говорит вам, как; комментарии говорят вам, почему"

- Джефф Этвуд (он же "Ужас кодинга")

Документирование кода - это описание его использования и функциональности для ваших пользователей. Хотя это может быть полезно в процессе разработки, основная целевая аудитория - это пользователи. В следующем разделе описывается, как и когда следует комментировать код.

Основы комментирования кода

Комментарии создаются в Python с помощью знака фунта (#) и должны быть краткими высказываниями, не превышающими нескольких предложений. Вот простой пример:

def hello_world():
    # A simple comment preceding a simple print statement
    print("Hello World")

Согласно PEP 8, комментарии должны иметь максимальную длину 72 символа. Это верно, даже если в вашем проекте максимальная длина строки будет больше рекомендуемых 80 символов. Если длина комментария превышает установленный лимит символов, целесообразно использовать для него несколько строк:

def hello_long_world():
    # A very long statement that just goes on and on and on and on and
    # never ends until after it's reached the 80 char limit
    print("Hellooooooooooooooooooooooooooooooooooooooooooooooooooooooo World")

Комментирование вашего кода служит множеству целей, включая:

Планирование и рецензирование: Когда вы разрабатываете новые части кода, может быть целесообразно сначала использовать комментарии как способ планирования или описания этого участка кода. Не забудьте удалить эти комментарии, когда фактический код будет реализован и проверен/тестирован:
```
# First step
# Second step
# Third step
```
Описание кода: Комментарии могут использоваться для объяснения смысла конкретных разделов кода:
```
# Attempt a connection based on previous settings. If unsuccessful,
# prompt user for new settings.
```
Описание алгоритмов: Когда используются алгоритмы, особенно сложные, может быть полезно объяснить, как работает алгоритм или как он реализован в вашем коде. Также может быть уместно описать, почему конкретный алгоритм был выбран вместо другого.
```
# Using quick sort for performance gains
```
Метки: Использование меток может быть использовано для обозначения определенных участков кода, где находятся известные проблемы или области улучшения. Некоторые примеры: BUG, FIXME и TODO.
```
# TODO: Add condition for when val is None
```

Комментарии к вашему коду должны быть краткими и целенаправленными. По возможности избегайте длинных комментариев. Кроме того, вы должны использовать следующие четыре основных правила, предложенные Джеффом Этвудом : :

Держите комментарии как можно ближе к описываемому коду. Комментарии, расположенные не рядом с описываемым кодом, раздражают читателя и легко пропускаются при обновлениях.
Не используйте сложное форматирование (например, таблицы или ASCII-рисунки). Сложное форматирование отвлекает внимание от содержания, и его трудно поддерживать в течение долгого времени.
Не включайте избыточную информацию. Предполагайте, что читатель кода имеет базовое представление о принципах программирования и синтаксисе языка.
Создайте свой код так, чтобы он сам себя комментировал. Самый простой способ понять код - это прочитать его. Если вы создаете код, используя четкие, легко понятные концепции, читатель сможет быстро понять ваш замысел.

Помните, что комментарии предназначены для читателей, в том числе и для вас самих, чтобы помочь им понять назначение и дизайн программного обеспечения.

Комментирование кода с помощью подсказки типов (Python 3.5+)

Подсказка типа была добавлена в Python 3.5 и является дополнительной формой помощи читателям вашего кода. По сути, она выводит четвертое предложение Джеффа на новый уровень. Она позволяет разработчику оформлять и объяснять части своего кода без комментариев. Вот быстрый пример:

def hello_name(name: str) -> str:
    return(f"Hello {name}")

Исследуя подсказки типов, можно сразу сказать, что функция ожидает, что входные данные name будут иметь тип str, или строка. Можно также сказать, что ожидаемый выход функции будет иметь тип str, или строка. Хотя подсказки типов помогают сократить количество комментариев, учитывайте, что это может также сделать дополнительную работу при создании или обновлении проектной документации.

Вы можете узнать больше о подсказках типов и проверке типов из этого видео, созданного Дэном Бейдером.

Документирование базы кода Python с помощью строк Docstrings

Теперь, когда мы узнали о комментировании, давайте углубимся в документирование кодовой базы Python. В этом разделе вы узнаете о docstrings и о том, как использовать их для документирования. Этот раздел разделен на следующие подразделы:

Основа докстрингов:Основа того, как докстринги работают внутри Python
Типы docstring: Различные "типы" docstring (функция, класс, метод класса, модуль, пакет и сценарий)
Форматы docstring: Различные "форматы" docstring (Google, NumPy/SciPy, reStructuredText и Epytext)

Документы Фоновые

Документирование кода Python сосредоточено на docstrings. Это встроенные строки, которые при правильной настройке могут помочь вашим пользователям и вам самим в работе с документацией вашего проекта. Наряду с docstrings, в Python есть встроенная функция help(), которая выводит docstring объектов на консоль. Вот быстрый пример:

>>> help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str
 |
 |  Create a new string object from the given object. If encoding or
 |  errors are specified, then the object must expose a data buffer
 |  that will be decoded using the given encoding and error handler.
 |  Otherwise, returns the result of object.__str__() (if defined)
 |  or repr(object).
 |  encoding defaults to sys.getdefaultencoding().
 |  errors defaults to 'strict'.
 # Truncated for readability

Как генерируется этот вывод? Поскольку в Python все является объектом, вы можете изучить каталог объекта с помощью команды dir(). Давайте сделаем это и посмотрим, что будет найдено:

>>> dir(str)
['__add__', ..., '__doc__', ..., 'zfill'] # Truncated for readability

В этом выводе каталога есть интересное свойство, __doc__. Если вы изучите это свойство, то обнаружите следующее:

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors are specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

Войла! Вы нашли, где в объекте хранятся документальные строки. Это означает, что вы можете напрямую манипулировать этим свойством. Однако для встроенных модулей существуют ограничения:

>>> str.__doc__ = "I'm a little string doc! Short and stout; here is my input and print me for my out"
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can't set attributes of built-in/extension type 'str'

Любым другим пользовательским объектом можно манипулировать:

def say_hello(name):
    print(f"Hello {name}, is it me you're looking for?")

say_hello.__doc__ = "A simple function that says hello... Richie style"

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

В Python есть еще одна возможность, которая упрощает создание doc-строк. Вместо того чтобы напрямую манипулировать свойством __doc__, стратегическое размещение строкового литерала непосредственно под объектом автоматически установит значение __doc__. Вот что происходит в том же примере, что и выше:

def say_hello(name):
    """A simple function that says hello... Richie style"""
    print(f"Hello {name}, is it me you're looking for?")

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

Вот так! Теперь вы поняли, что такое докстринги. Настало время узнать о различных типах строк и о том, какую информацию они должны содержать.

Типы строк

Соглашения о строках описаны в PEP 257. Их цель - предоставить пользователям краткий обзор объекта. Они должны быть достаточно краткими, чтобы их было легко поддерживать, но при этом достаточно подробными, чтобы новые пользователи могли понять их назначение и то, как использовать документированный объект.

Во всех случаях в документах должен использоваться формат строки с тройными двойными кавычками ("""). Это следует делать независимо от того, является ли документ многострочным или нет. Как минимум, doc-строка должна представлять собой краткое изложение того, что вы описываете, и должна быть заключена в одну строку:

"""This is a quick summary line used as a description of the object."""

Многострочные документообороты используются для более подробного описания объекта, выходящего за рамки краткого описания. Все многострочные документообороты состоят из следующих частей:

Однострочная строка резюме
Пустая строка, продолжающая резюме
Любая дальнейшая разработка для docstring
Еще одна пустая строка

"""This is the summary line

This is the further elaboration of the docstring. Within this section,
you can elaborate further on details as appropriate for the situation.
Notice that the summary and the elaboration is separated by a blank new
line.
"""

# Notice the blank line above. Code should continue on this line.

Все документообороты должны иметь ту же максимальную длину символов, что и комментарии (72 символа). Докстринги можно разделить на три основные категории:

Докстринги классов: Классы и методы классов
Докстринги пакетов и модулей: Пакеты, модули и функции
Докстринги скриптов: Скрипты и функции

Класс Docstrings

Документы класса создаются для самого класса, а также для любых методов класса. Докстринги размещаются сразу после класса или метода класса с отступом в один уровень:

class SimpleClass:
    """Class docstrings go here."""

    def say_hello(self, name: str):
        """Class method docstrings go here."""

        print(f'Hello {name}')

Документы классов должны содержать следующую информацию:

Краткое описание его назначения и поведения
Любые публичные методы с кратким описанием
Любые свойства класса (атрибуты)
Все, что связано с интерфейсом для подклассификаторов, если класс предназначен для подклассификации

Параметры конструктора класса должны быть задокументированы в док-строке метода класса __init__. Отдельные методы должны быть задокументированы с помощью своих отдельных документов. Документация метода класса должна содержать следующее:

Краткое описание того, что представляет собой метод и для чего он используется
Все передаваемые аргументы (как обязательные, так и необязательные), включая аргументы с ключевыми словами
Обозначьте все аргументы, которые считаются необязательными или имеют значение по умолчанию
Любые побочные эффекты, возникающие при выполнении метода
Любые исключения, которые поднимаются
Любые ограничения на то, когда метод может быть вызван

Давайте рассмотрим простой пример класса данных, который представляет животное. Этот класс будет содержать несколько свойств класса, свойств экземпляра, __init__ и один метод экземпляра:

class Animal:
    """
    A class used to represent an Animal

    ...

    Attributes
    ----------
    says_str : str
        a formatted string to print out what the animal says
    name : str
        the name of the animal
    sound : str
        the sound that the animal makes
    num_legs : int
        the number of legs the animal has (default 4)

    Methods
    -------
    says(sound=None)
        Prints the animals name and what sound it makes
    """

    says_str = "A {name} says {sound}"

    def __init__(self, name, sound, num_legs=4):
        """
        Parameters
        ----------
        name : str
            The name of the animal
        sound : str
            The sound the animal makes
        num_legs : int, optional
            The number of legs the animal (default is 4)
        """

        self.name = name
        self.sound = sound
        self.num_legs = num_legs

    def says(self, sound=None):
        """Prints what the animals name is and what sound it makes.

        If the argument `sound` isn't passed in, the default Animal
        sound is used.

        Parameters
        ----------
        sound : str, optional
            The sound the animal makes (default is None)

        Raises
        ------
        NotImplementedError
            If no sound is set for the animal or passed in as a
            parameter.
        """

        if self.sound is None and sound is None:
            raise NotImplementedError("Silent Animals are not supported!")

        out_sound = self.sound if sound is None else sound
        print(self.says_str.format(name=self.name, sound=out_sound))

Строки пакетов и модулей

Документация пакета должна располагаться в верхней части __init__.py файла пакета. В этой строке должны быть перечислены модули и подпакеты, экспортируемые пакетом.

Документация модулей похожа на документацию классов. Вместо классов и методов классов документируется модуль и все функции, находящиеся в нем. Документация модуля размещается в верхней части файла, даже перед импортом. Документация модуля должна содержать следующее:

Краткое описание модуля и его назначение
Список всех классов, исключений, функций и любых других объектов, экспортируемых модулем

Документальная строка для функции модуля должна включать те же элементы, что и метод класса:

Краткое описание того, что представляет собой функция и для чего она используется
Все передаваемые аргументы (как обязательные, так и необязательные), включая аргументы ключевых слов
Обозначьте все аргументы, которые считаются необязательными
Любые побочные эффекты, возникающие при выполнении функции
Любые исключения, которые поднимаются
Любые ограничения на то, когда функция может быть вызвана

Докстринги сценариев

Сценарии считаются однофайловыми исполняемыми файлами, запускаемыми из консоли. Докстринги для скриптов размещаются в верхней части файла и должны быть достаточно хорошо документированы, чтобы пользователи могли достаточно хорошо понять, как использовать скрипт. Она должна быть пригодна для использования в случае, если пользователь неправильно передал параметр или использовал опцию -h.

Если вы используете argparse, то документацию по параметрам можно опустить, при условии, что они были правильно задокументированы в параметре help функции argparser.parser.add_argument. Рекомендуется использовать __doc__ для параметра description внутри конструктора argparse.ArgumentParser. Ознакомьтесь с нашим руководством по Библиотекам разбора командной строки для получения более подробной информации об использовании argparse и других распространенных парсеров командной строки.

Наконец, любые пользовательские или сторонние импорты должны быть перечислены в документах, чтобы пользователи могли знать, какие пакеты могут потребоваться для выполнения скрипта. Вот пример сценария, который используется для простой распечатки заголовков столбцов электронной таблицы:

"""Spreadsheet Column Printer

This script allows the user to print to the console all columns in the
spreadsheet. It is assumed that the first row of the spreadsheet is the
location of the columns.

This tool accepts comma separated value files (.csv) as well as excel
(.xls, .xlsx) files.

This script requires that `pandas` be installed within the Python
environment you are running this script in.

This file can also be imported as a module and contains the following
functions:

    * get_spreadsheet_cols - returns the column headers of the file
    * main - the main function of the script
"""

import argparse

import pandas as pd


def get_spreadsheet_cols(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Parameters
    ----------
    file_loc : str
        The file location of the spreadsheet
    print_cols : bool, optional
        A flag used to print the columns to the console (default is
        False)

    Returns
    -------
    list
        a list of strings used that are the header columns
    """

    file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        'input_file',
        type=str,
        help="The spreadsheet file to pring the columns of"
    )
    args = parser.parse_args()
    get_spreadsheet_cols(args.input_file, print_cols=True)


if __name__ == "__main__":
    main()

Форматы строк

Вы, наверное, заметили, что во всех примерах, приведенных в этом учебнике, использовалось специфическое форматирование с общими элементами: Arguments, Returns и Attributes. Существуют специальные форматы docstrings, которые могут быть использованы для того, чтобы парсеры docstring и пользователи имели знакомый и известный формат. Форматирование, используемое в примерах этого руководства, представляет собой формат docstrings в стиле NumPy/SciPy. Некоторые из наиболее распространенных форматов следующие:

Formatting Type	Description	Supported by Sphynx	Formal Specification
Google docstrings	Рекомендуемая форма документации Google	Yes	No
reStructuredText	Официальный стандарт документации по Python; не очень удобен для новичков, но обладает широкими возможностями	Yes	Yes
NumPy/SciPy docstrings	Комбинация reStructuredText и Google Docstrings в NumPy	Yes	Yes
Epytext	Адаптация Epydoc для Python; отлично подходит для Java-разработчиков.	Not officially	Yes

Выбор формата docstring зависит от вас, но вы должны придерживаться одного и того же формата во всем документе/проекте. Ниже приведены примеры каждого типа, чтобы дать вам представление о том, как выглядит каждый формат документации.

Пример Google Docstrings

"""Gets and prints the spreadsheet's header columns

Args:
    file_loc (str): The file location of the spreadsheet
    print_cols (bool): A flag used to print the columns to the console
        (default is False)

Returns:
    list: a list of strings representing the header columns
"""

reStructuredText Пример

"""Gets and prints the spreadsheet's header columns

:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
    (default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""

Пример докстрингов NumPy/SciPy

"""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
    The file location of the spreadsheet
print_cols : bool, optional
    A flag used to print the columns to the console (default is False)

Returns
-------
list
    a list of strings representing the header columns
"""

Пример эпитекста

"""Gets and prints the spreadsheet's header columns

@type file_loc: str
@param file_loc: The file location of the spreadsheet
@type print_cols: bool
@param print_cols: A flag used to print the columns to the console
    (default is False)
@rtype: list
@returns: a list of strings representing the header columns
"""

Документирование проектов на Python

Python-проекты бывают самых разных форм, размеров и назначений. То, как вы документируете свой проект, должно соответствовать конкретной ситуации. Помните о том, кто будет пользователями вашего проекта, и адаптируйтесь к их потребностям. В зависимости от типа проекта рекомендуется использовать определенные аспекты документации. Общая схема проекта и документации к нему должна быть следующей:

project_root/
│
├── project/  # Project source code
├── docs/
├── README
├── HOW_TO_CONTRIBUTE
├── CODE_OF_CONDUCT
├── examples.py

Проекты в целом можно разделить на три основных типа: Частные, Общие и Общественные/Открытый источник.

Частные проекты

Частные проекты - это проекты, предназначенные только для личного использования и, как правило, не предоставляемые другим пользователям или разработчикам. Документация по таким проектам может быть довольно скудной. Есть несколько рекомендуемых частей, которые следует добавлять по мере необходимости:

Readme: Краткое описание проекта и его цели. Включите любые специальные требования к установке или эксплуатации проекта.
examples.py: Файл сценария Python, в котором приведены простые примеры использования проекта.

Помните, что хотя частные проекты предназначены лично для вас, вы также считаетесь пользователем. Подумайте о том, что может вас смутить в будущем, и обязательно отразите это в комментариях, документах или readme.

Общие проекты

Общие проекты - это проекты, в которых вы сотрудничаете с несколькими другими людьми в разработке и/или использовании проекта. При этом "заказчиком" или пользователем проекта остаетесь вы сами и те немногие, кто также использует проект.

Документация должна быть немного более строгой, чем это необходимо для частного проекта, в основном для того, чтобы помочь принять новых участников в проект или предупредить авторов/пользователей о новых изменениях в проекте. Рекомендуется добавить в проект следующие части:

Readme: Краткое описание проекта и его цели. Включите все особые требования к установке и работе проекта. Кроме того, добавьте все основные изменения с момента выхода предыдущей версии.
examples.py: Файл сценария на языке Python, в котором приводятся простые примеры использования проектов.
Как вносить вклад: Здесь должно быть указано, как новые участники проекта могут начать вносить свой вклад.

Публичные и открытые проекты

Публичные проекты и проекты с открытым исходным кодом - это проекты, которые предназначены для совместного использования с большой группой пользователей и могут включать в себя большие команды разработчиков. В таких проектах документации по проекту должно уделяться такое же большое внимание, как и разработке самого проекта. Рекомендуется добавить в проект следующие части:

Readme: Краткое описание проекта и его цели. Укажите все особые требования к установке и эксплуатации проекта. Кроме того, добавьте все основные изменения с момента выхода предыдущей версии. Наконец, добавьте ссылки на дополнительную документацию, сообщения об ошибках и любую другую важную информацию о проекте. Дэн Бейдер составил отличное руководство о том, что должно быть включено в readme.
Как внести вклад: Здесь должно быть указано, чем могут помочь новые участники проекта. Это включает разработку новых функций, исправление известных проблем, добавление документации, добавление новых тестов или сообщение о проблемах.
Кодекс поведения: Определяет, как другие участники должны относиться друг к другу при разработке или использовании вашего программного обеспечения. Здесь также указано, что произойдет, если этот кодекс будет нарушен. Если вы используете Github, можно сгенерировать шаблон Кодекса поведения с рекомендуемыми формулировками. Для проектов с открытым исходным кодом, в частности, рассмотрите возможность добавления этого.
License: Файл в виде обычного текста, описывающий лицензию, которую использует ваш проект. Для проектов с открытым исходным кодом особенно важно добавить это.
docs: Папка, содержащая дополнительную документацию. В следующем разделе более подробно описано, что должно быть включено и как организовать содержимое этой папки.

Четыре основных раздела папки `docs`

Даниэль Прочида выступил с замечательным докладом PyCon 2017 и последующим постом в блоге о документировании проектов на Python. Он упоминает, что все проекты должны иметь следующие четыре основных раздела, которые помогут вам сфокусировать свою работу:

Учебники: Уроки, которые ведут читателя за руку через серию шагов по завершению проекта (или значимого упражнения). Направлены на обучение пользователя.
How-To Guides: Руководства, которые проводят читателя через шаги, необходимые для решения общей проблемы (проблемно-ориентированные рецепты).
References: Объяснения, которые проясняют и освещают конкретную тему. Направлены на понимание.
Объяснения: Технические описания механизмов и того, как ими управлять (ключевые классы, функции, API и так далее). Подумайте о статье в энциклопедии.

В следующей таблице показано, как все эти разделы соотносятся друг с другом, а также их общее назначение:

	Most Useful When We’re Studying	Most Useful When We’re Coding
Practical Step	Tutorials	How-To Guides
Theoretical Knowledge	Explanation	Reference

В конечном итоге вы хотите убедиться, что ваши пользователи имеют доступ к ответам на любые вопросы, которые у них могут возникнуть. Организовав свой проект таким образом, вы сможете легко ответить на эти вопросы в формате, в котором они смогут быстро сориентироваться.

Инструменты и ресурсы для документирования

Документирование кода, особенно в больших проектах, может оказаться сложной задачей. К счастью, есть несколько инструментов и ссылок, которые помогут вам начать:

Tool	Description
Sphinx	A collection of tools to auto-generate documentation in multiple formats
Epydoc	A tool for generating API documentation for Python modules based on their docstrings
Read The Docs	Automatic building, versioning, and hosting of your docs for you
Doxygen	A tool for generating documentation that supports Python as well as multiple other languages
MkDocs	A static site generator to help build project documentation using the Markdown language. Check out Build Your Python Project Documentation With MkDocs to learn more.
pycco	A “quick and dirty” documentation generator that displays code and documentation side by side. Check out our tutorial on how to use it for more info.
`doctest`	A standard-library module for running usage examples as automated tests. Check out Python’s doctest: Document and Test Your Code at Once

Наряду с этими инструментами существует несколько дополнительных руководств, видео и статей, которые могут быть полезны при документировании вашего проекта:

Иногда лучший способ научиться - это подражать другим. Вот несколько отличных примеров проектов, в которых хорошо используется документация:

Django: Docs (Source)
Requests: Docs (Source)
Клик: Docs (Source)
Панды: Документы (Источник)

С чего начать?

Документация проектов имеет простую последовательность:

Без документации
Некоторая документация
Полная документация
Хорошая документация
Отличная документация

Если вы не знаете, куда двигаться дальше с документацией, посмотрите, на каком этапе находится ваш проект по отношению к вышеописанной прогрессии. Есть ли у вас какая-нибудь документация? Если нет, то начните с этого. Если у вас есть документация, но не хватает некоторых ключевых файлов проекта, начните с их добавления.

В конце концов, не отчаивайтесь и не перегружайте себя объемом работы, необходимой для документирования кода. Как только вы начнете документировать свой код, вам будет легче продолжать. Не стесняйтесь оставлять комментарии, если у вас есть вопросы, или обращайтесь к команде Real Python Team в социальных сетях, и мы вам поможем.

Вернуться на верх