TOC

Документирование кода Python: полное руководство

Документирование кода Python: полное руководство

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

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

  1. Why Documenting Your Code Is So Important: Введение в документацию и ее важность

  2. Commenting vs. Documenting Code: Обзор основных различий между комментированием и документированием, а также подходящее время и способы использования комментирования.

  3. Documenting Your Python Code Base Using Docstrings: Подробное описание строк документации для классов, методов класса, функций, модулей, пакетов и скриптов, а также того, что должно быть найдено в каждом из них

  4. Documenting Your Python Projects: Необходимые элементы и то, что они должны содержать для ваших проектов Python

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

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

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

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

-Guido van Rossum

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

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

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

«Неважно, насколько хорошо ваше программное обеспечение, потому чтоif the documentation is not good enough, people will not use it.»

-Daniele Procida

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

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

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

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

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

-Jeff Atwood (aka Coding Horror)

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

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

Комментарии создаются в 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")

Комментирование вашего кода служитmultiple purposes, including:

  • Planning and Reviewing: Когда вы разрабатываете новые части своего кода, может быть целесообразно сначала использовать комментарии как способ планирования или обрисовки этой части кода. Не забудьте удалить эти комментарии после того, как фактическое кодирование было реализовано и проверено / протестировано: 

    # First step
# Second step
# Third step

  • Code Description: Комментарии могут быть использованы для объяснения цели определенных разделов кода: 

    # Attempt a connection based on previous settings. If unsuccessful,
# prompt user for new settings.

  • Algorithmic Description: Когда используются алгоритмы, особенно сложные, может быть полезно объяснить, как работает алгоритм или как он реализован в вашем коде. Также может быть целесообразно описать, почему определенный алгоритм был выбран над другим. 

    # Using quick sort for performance gains

  • Tagging: Использование тегов может использоваться для обозначения определенных участков кода, где обнаружены известные проблемы или области, требующие улучшения. Вот некоторые примеры:BUG,FIXME иTODO. 

    # TODO: Add condition for when val is None

Комментарии к вашему коду должны быть краткими и целенаправленными. Избегайте использования длинных комментариев, когда это возможно. Кроме того, вы должны использовать следующие четыре основных правила в качествеsuggested by Jeff Atwood:

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

  2. Не используйте сложное форматирование (например, таблицы или рисунки ASCII). Сложное форматирование приводит к отвлечению контента и может быть сложным для поддержания в течение долгого времени.

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

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

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

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

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

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

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

Вы можете узнать больше о подсказках типов и проверке типов изthis video created by Dan Bader.

Документирование вашей базы кода Python с использованием строк документации

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

  1. Docstrings Background: Справочная информация о том, как строки документации работают внутри Python

  2. Docstring Types: Различные «типы» строк документации (функция, класс, метод класса, модуль, пакет и сценарий)

  3. Docstring Formats: Различные «форматы» строк документации (Google, NumPy / SciPy, reStructured Text и Epytext)

Фон Строки

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

>>> 

>>> 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 "", line 1, in 
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__. Вот что происходит с тем же примером, что и выше: 

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. Их цель - предоставить вашим пользователям краткий обзор объекта. Они должны быть достаточно краткими, чтобы их было легко обслуживать, но при этом быть достаточно сложными, чтобы новые пользователи могли понять их назначение и способы использования документированного объекта.

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

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

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

  • Сводная строка в одну строку

  • Пустая строка после резюме

  • Любая дальнейшая разработка для документации

  • Еще одна пустая строка 

"""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 символа). Строки документов можно далее разбить на три основные категории:

  • Class Docstrings: Класс и методы класса

  • Package and Module Docstrings: Пакет, модули и функции

  • Script Docstrings: Скрипт и функции

Класс Docstrings

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

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

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

        print(f'Hello {name}')

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

  • Краткое описание его цели и поведения

  • Любые публичные методы, вместе с кратким описанием

  • Любые свойства класса (атрибуты)

  • Все, что связано с интерфейсом для подклассов, если класс предназначен для подклассов

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

  • Краткое описание того, что представляет собой метод и для чего он используется

  • Любые передаваемые аргументы (как обязательные, так и необязательные), включая ключевые слова

  • Пометьте любые аргументы, которые считаются необязательными или имеют значение по умолчанию

  • Любые побочные эффекты, возникающие при выполнении метода

  • Любые исключения, которые возникают

  • Любые ограничения на то, когда метод может быть вызван

Давайте рассмотрим простой пример класса данных, представляющего Animal. Этот класс будет содержать несколько свойств класса, свойства экземпляра,__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. Эта строка документации должна содержать список модулей и подпакетов, которые экспортируются этим пакетом.

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

  • Краткое описание модуля и его назначение

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

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

  • Краткое описание того, что это за функция и для чего она используется

  • Любые передаваемые аргументы (как обязательные, так и необязательные), включая ключевые слова

  • Пометьте любые аргументы, которые считаются необязательными

  • Любые побочные эффекты, возникающие при выполнении функции

  • Любые исключения, которые возникают

  • Любые ограничения на то, когда функция может быть вызвана

Script Docstrings

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

Если вы используетеargparse, вы можете опустить документацию по конкретным параметрам, предполагая, что она правильно задокументирована в параметреhelp функцииargparser.parser.add_argument. Рекомендуется использовать__doc__ для параметраdescription в конструктореargparse.ArgumentParser. Ознакомьтесь с нашим руководством поCommand-Line Parsing Libraries, чтобы узнать больше о том, как использовать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. Существуют определенные форматы строк документации, которые могут использоваться для помощи анализаторам строк документации, и пользователи имеют знакомый и известный формат. Форматирование, используемое в примерах из этого руководства, представляет собой строки документации в стиле NumPy / SciPy. Вот некоторые из наиболее распространенных форматов:

Тип форматирования Описание При поддержке Sphynx Формальная спецификация

Строки документации Google

Форма документации, рекомендуемая Google

Yes

No

реструктурированный текст

Официальный стандарт документации Python; Не для новичков, но с богатым набором функций

Yes

Yes

NumPy/SciPy docstrings

Сочетание reStructured и Google Docstrings в NumPy

Yes

Yes

Эпитекст

Адаптация Epydoc для Python; Отлично подходит для разработчиков Java

Не официально

Yes

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

Пример 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
"""
reStructured Text Example 
"""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 Docstrings Example
"""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, в котором приведены простые примеры использования проектов.

  • How to Contribute: Это должно включать в себя то, как новые участники проекта могут начать вносить свой вклад.

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

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

  • Readme: Краткое описание проекта и его цели. Включите любые специальные требования для установки или эксплуатации проектов. Кроме того, добавьте любые важные изменения с предыдущей версии. Наконец, добавьте ссылки на дополнительную документацию, отчеты об ошибках и любую другую важную информацию для проекта. Дэн Бейдер составилa great tutorial о том, что все должно быть включено в ваш файл readme.

  • How to Contribute: Здесь следует указать, как новые участники проекта могут помочь. Это включает разработку новых функций, исправление известных проблем, добавление документации, добавление новых тестов или создание отчетов о проблемах.

  • Code of Conduct: Определяет, как другие участники должны относиться друг к другу при разработке или использовании вашего программного обеспечения. Здесь также указано, что произойдет, если этот код будет нарушен. Если вы используете Github, можно создать Кодекс поведенияtemplate с рекомендуемой формулировкой. Особенно для проектов с открытым исходным кодом, рассмотрите возможность добавления этого.

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

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

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

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

  • Tutorials: Уроки, которые проводят читателя за руку через серию шагов для выполнения проекта (или содержательное упражнение). Ориентирован на обучение пользователей.

  • How-To Guides: Руководства, которые проводят читателя по шагам, необходимым для решения общей проблемы (проблемно-ориентированные рецепты).

  • References: Пояснения, которые проясняют и освещают конкретную тему. Направлен на понимание.

  • Explanations: технические описания оборудования и способы управления им (ключевые классы, функции, API и т. д.). Вспомните статью энциклопедии.

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

Самое полезное, когда мы учимся Самое полезное, когда мы программируем

Практический шаг

Учебники

Практические руководства

Теоретические знания

объяснение

Ссылка

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

Документация Инструменты и ресурсы

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

Tool Описание

сфинкс

Набор инструментов для автоматического создания документации в нескольких форматах

Эпидок

Инструмент для создания документации API для модулей Python на основе их строк документации.

Прочтите документы

Автоматическое создание, управление версиями и размещение ваших документов для вас

Doxygen

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

MkDocs

Генератор статических сайтов, помогающий создавать документацию по проекту с использованием языка Markdown.

пикко

Генератор «быстрой и грязной» документации, отображающий код и документацию бок о бок. Проверьтеour tutorial on how to use it for more info.

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

  1. Кэрол Уиллинг - Практический сфинкс - PyCon 2018

  2. Даниэле Прочида - Разработка на основе документации - Уроки проекта Django - PyCon 2016

  3. Эрик Хольшер - Документирование вашего проекта с помощью Sphinx & Read the Docs - PyCon 2016

  4. Титус Браун, Луис Ирбер - Создание, построение, тестирование и документирование проекта Python: практический HOWTO - PyCon 2016

  5. Официальная документация с реструктурированным текстом

  6. Учебник по реструктурированному тексту Sphinx

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

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

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

  1. Нет документации

  2. Некоторая документация

  3. Полная документация

  4. Хорошая документация

  5. Отличная документация

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

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

Related