как правильно документировать код python
Документирование кода в Python. PEP 257
PEP 257 описывает соглашения, связанные со строками документации python, рассказывает о том, как нужно документировать python код.
Что такое строки документации?
Все модули должны, как правило, иметь строки документации, и все функции и классы, экспортируемые модулем также должны иметь строки документации. Публичные методы (в том числе __init__) также должны иметь строки документации. Пакет модулей может быть документирован в __init__.py.
Для согласованности, всегда используйте «»»triple double quotes»»» для строк документации. Используйте r»»»raw triple double quotes»»», если вы будете использовать обратную косую черту в строке документации.
Существует две формы строк документации: однострочная и многострочная.
Однострочные строки документации
Однострочники предназначены для действительно очевидных случаев. Они должны умещаться на одной строке. Например:
Используйте тройные кавычки, даже если документация умещается на одной строке. Потом будет проще её дополнить.
Закрывающие кавычки на той же строке. Это смотрится лучше.
Нет пустых строк перед или после документации.
Однострочная строка документации не должна быть «подписью» параметров функции / метода (которые могут быть получены с помощью интроспекции). Не делайте:
Этот тип строк документации подходит только для C функций (таких, как встроенные модули), где интроспекция не представляется возможной. Тем не менее, возвращаемое значение не может быть определено путем интроспекции. Предпочтительный вариант для такой строки документации будет что-то вроде:
(Конечно, «Do X» следует заменить полезным описанием!)
Многострочные строки документации
Многострочные строки документации состоят из однострочной строки документации с последующей пустой строкой, а затем более подробным описанием. Первая строка может быть использована автоматическими средствами индексации, поэтому важно, чтобы она находилась на одной строке и была отделена от остальной документации пустой строкой. Первая строка может быть на той же строке, где и открывающие кавычки, или на следующей строке. Вся документация должна иметь такой же отступ, как кавычки на первой строке (см. пример ниже).
Строки документации скрипта (самостоятельной программы) должны быть доступны в качестве «сообщения по использованию», напечатанной, когда программа вызывается с некорректными или отсутствующими аргументами (или, возможно, с опцией «-h», для помощи). Такая строка документации должна документировать функции программы и синтаксис командной строки, переменные окружения и файлы. Сообщение по использованию может быть довольно сложным (несколько экранов) и должно быть достаточным для нового пользователя для использования программы должным образом, а также полный справочник со всеми вариантами и аргументами для искушенного пользователя.
Строки документации модуля должны, как правило, перечислять классы, исключения, функции (и любые другие объекты), которые экспортируются модулем, с краткими пояснениями (в одну строчку) каждого из них. (Эти строки, как правило, дают меньше деталей, чем первая строка документации к объекту). Строки документации пакета модулей (т.е. строка документации в __init__.py) также должны включать модули и подпакеты.
Строки документации функции или метода должны обобщить его поведение и документировать свои аргументы, возвращаемые значения, побочные эффекты, исключения, дополнительные аргументы, именованные аргументы, и ограничения на вызов функции.
Строки документации класса обобщают его поведение и перечисляют открытые методы и переменные экземпляра. Если класс предназначен для подклассов, и имеет дополнительный интерфейс для подклассов, этот интерфейс должен быть указан отдельно (в строке документации). Конструктор класса должен быть задокументирован в документации метода __init__. Отдельные методы должны иметь свои строки документации.
И, напоследок, пример:
А ещё больше примеров можно посмотреть в стандартной библиотеке python (например, в папке Lib вашего интерпретатора python).
Docstrings: документирование кода в Python
Хочешь знать больше о Python?
Подпишись на наш канал о Python в Telegram!
В статье, опубликованной на сайте pythonist.ru, рассмотрены строки документации в Python. Давайте разберемся, как и зачем их использовать.
Строки документации (docstrings) в Python — это строковые литералы, которые пишутся сразу после определения функции, метода, класса или модуля. Давайте рассмотрим пример.
Пример 1: Строки документации.
Здесь строковый литерал:
Принимает число n, возвращает квадрат числа n
Комментарии vs строки документации Python
Комментарии Python
Комментарии — это описания, которые помогают программистам лучше понять назначение и функциональность программы. Они полностью игнорируются интерпретатором Python.
В Python мы используем символ # для написания однострочного комментария. Например,
Комментарии Python с использованием строк
Если мы не присваиваем строки какой-либо переменной, они ведут себя как комментарии. Например,
Примечание. Мы используем тройные кавычки для многострочных строк.
Строки документации Python
Как упоминалось выше, строки документации в Python — это строки, которые пишутся сразу после определения функции, метода, класса или модуля (как в примере 1). Они используются для документирования нашего кода.
Атрибут __doc__
Всякий раз, когда строковые литералы присутствуют сразу после определения функции, модуля, класса или метода, они становятся специальным атрибутом __doc__ этого объекта. Позже мы можем использовать этот атрибут для получения этой строки документации.
Пример 2: Вывод на экран строки документации.
Принимает число n, возвращает квадрат числа n
Теперь давайте посмотрим на строки документации для встроенной функции print() :
Пример 3: строки документации для встроенной функции print().
Здесь мы можем видеть, что документация функции print() представлена как атрибут __doc__ этой функции.
Однострочные строки документации в Python
Однострочные строки документации должны помещаться на одной строке.
Стандартные соглашения для написания однострочных строк документации:
Давайте посмотрим на пример ниже.
Пример 4: Однострочная строка документации для функции.
Многострочные строки документации в Python
Многострочные строки документации состоят из резюмирующей однострочной строки документации, за которой следует пустая строка, а затем более подробное описание.
Документ PEP 257 предоставляет стандартные соглашения для написания многострочных строк документации для различных объектов.
Некоторые из них перечислены ниже:
1. Строки документации для модулей Python
Строки документации пишутся в начале файла Python.
Пример 4: строки документации модуля Python.
2. Строки документации для функций Python
Пример 5: строки документации для функций Python.
3. Строки документации для классов Python
Пример 6: строки документации для класса Python.
Предположим, у нас есть файл Person.py со следующим кодом:
Мы можем использовать следующий код для доступа только к строкам документации класса Person :
Использование функции help() для строк документации
Мы также можем использовать функцию help() для чтения строк документации, связанных с различными объектами.
Пример 7: чтение строк документации с помощью функции help().
Мы можем использовать функцию help() для класса Person из Примера 6:
Здесь мы видим, что функция help() получает строки документации класса Person вместе с методами, связанными с этим классом.
4. Строки документации для скриптов Python
5. Строки документации для пакетов Python
Строки документации для пакета Python записываются в файл __init__.py пакета. Они должны содержать все доступные модули и подпакеты, экспортируемые пакетом.
Форматы строк документации
Мы можем писать строки документации во многих форматах, таких как reStructured text (reST), формат Google или формат документации NumPy. Чтобы узнать больше, перейдите по ссылке.
Мы также можем генерировать документацию из строк документации, используя такие инструменты, как Sphinx. Чтобы узнать больше, смотрите официальную документацию Sphinx.
Автоматическая визуализация python-кода. Часть четвертая: поддержка документирования
Ссылки на предыдущие части:
Среда, поддерживающая графическое представление кода
В четвертой части статьи речь пойдет о поддержке процесса документирования.
Вокруг да около
Посмотрим, что доступно разработчику в плане работы с документацией.
Питон поддерживает строки документации для модулей, классов и функций. Это хорошо. Комментарии также иногда используются для документирования.
Существуют генераторы документации, вроде doxygen и sphinx. Это тоже хорошо.
Однако иногда хочется немного большего. Бывают случаи, когда описание функции или класса становится слишком большим и строки документации (или комментарии) излишне «разбухают». Количество не исполняемых строк начинает подавлять количество исполняемых, что может затруднить чтение из-за размытости кода. Еще одна проблема — это различные диаграммы. В текст готовую картинку не вставишь. Можно вставить только описание диаграммы, например Plant UML диаграмму, но даже в этом случае нужно обеспечить рендеринг, что сделать непосредственно в тексте программы затруднительно.
Решение проблемы простое — сохранить пространное описание в отдельном файле, а в коде оставить пометку, о том, что документация находится там-то. Отдельный файл можно рендерить подходящим образом в нужный момент. А пометка в коде желательно должна быть интерактивной, то есть обеспечивать переход к документации по одному щелчку мыши. В принципе, пометку в тексте программы можно рассматривать шире: это может быть и URL, и какое-то место в другом файле исходного текста, и картинка, и внешний файл с документацией.
Легко представить себе и обратную ссылку. Скажем, документация упоминает какой-либо класс из исходного текста программы или даже конкретный блок кода. Для этого случая тоже хорошо было бы обеспечить быстрый переход к нужному фрагменту кода.
Отдельного обсуждения заслуживает и вопрос о формате файлов документации. В последнее время популярность набрал markdown, несмотря на критику в его адрес (например здесь). Скажем, github автоматически показывает markdown документацию при заходе на страницу проекта, что довольно удобно. При этом нужно выполнить очень простое интуитивно понятное соглашение об именовании и расположении файла. Инструментария для работы с markdown тоже в достатке, так что этот формат является хорошим кандидатом.
Реализация в Codimension IDE
Наряду с текстовым, Codimension IDE поддерживает графическое представление кода. Также IDE поддерживает язык разметки. Поэтому задача добавления нового графического элемента для отображения ссылок на документацию является достаточно простой.
Для начала сформулируем требования к новой функциональности в компактном виде:
Markdown и рендеринг
Codimension IDE использует qutepart в качестве компонента редактора текста, а qutepart, в свою очередь, поддерживает markdown из коробки: подсветка синтаксиса уже сделана. Для автоматического рендеринга можно воспользоваться тем же подходом, что и для питон файлов. Основное поле разбивается на две части. Слева — текст markdown, а справа — рендеринг:
Редактирование markdown с автоматическим рендерингом
Рендеринг, конечно, осуществляется автоматически. IDE определяет паузу в редактировании текста и обновляет рендеринг, если необходимо. Для режима просмотра markdown левая часть с текстовым редактором подавляется.
Для рендеренга удобным оказалось использовать библиотеку mistune, которая позволяет быстро преобразовать текст в HTML. Готовый HTML отправляется QT компоненту для отображения. Библиотека mistune также оказалась достаточно гибкой для того, чтобы добавить распознование описаний диаграмм plantUML. Диаграмма добавляется как блок кода с соответствующим языком, например:
Распознавание диаграмм plantUML
plantUML поддерживает разные типы диаграмм. Для Codimension описание диаграммы прозрачно, то есть оно не анализируется, а как есть передается plantUML. Соответственно, все поддерживаемые типы будут отображаться в окне просмотра. На момент написания статьи plantUML поддерживал следующие тэги начала/конца разных типов диаграмм:
Из библиотеки QT используется компонент QTextBrowser, который поддерживает HTML. К сожалению, поддерживаемый диалект HTML ограничен, поэтому конечный результат почти невозможно сделать идеальным. Возможно, этот недостаток удастся исправить в будущем.
Вмешательства потребовала и обработка щелчков мыши на ссылках. В ссылке может оказаться что-то из следующего:
Графический элемент
Графический элемент имеет смысл вводить с помощью нового CML комментария, аналогично тому, как это уже сделано, например, для групп. CML поддерживает атрибуты, что также потребуется для нового графического элемента.
Ссылка на документацию в некотором смысле подобна комментарию — она не является выполняемой строчкой программы, но сообщает дополнительную информацию о каком-то контексте. Codimension IDE распознает несколько типов комментариев: независимые, лидирующие и боковые. Для документации кажется разумным поддержать независимые и лидирующие графические элементы так же, как это сделано для комментариев. С боковым элементом для документации возникает неясность. Дело в том, как боковые комментарии отрисовываются для многострочного блока кода. Справа от блока рисуется прямоугольник, покрывающий все строчки бокового комментария с поддержкой соответствия номеров строк. А что делать, если CML doc встретился в середине бокового комментария, не совсем ясно. С другой стороны, ссылка все равно ведет к какому-то другому месту, поэтому поддержка боковых CML doc выглядит излишней — контекст конкретной строки в блоке кода очень узок. Поддержка боковых CML doc для функций и классов так же кажется излишней. Поэтому на данном этапе будут реализованы только независимые и лидирующие CML doc. Стоит заметить, что если в будущем появится обоснованная необходимость поддержки боковых CML doc и хорошая идея как их отображать, то такую функциональность можно будет добавить.
Обсудим что нужно показывать в графическом элементе. Очевидно, что нужен текст для элемента. Текст задается разработчиком и подсказывает, на что указывает ссылка. Ранее упоминалось, что желательно обеспечить переход на документацию по одному щелчку мыши. Текст графического элемента не подходит, потому что должна соблюдаться преемственность между поведением других элементов — по щелчку мыши производится выделение графического элемента. Однако решить задачу просто: можно добавить иконку, например, слева от текста, а щелчок на иконке приведет к переходу.
Теперь ясен и список атрибутов для CML doc комментария:
Вот пример кода, использующего CML doc, и его графическое представление:
Независимый и лидирующий CML doc комментарии
Разница между лидирующим и независимым элементами только в том, куда ведет соединитель: либо к конкретному блоку, либо к соединителю между блоками.
Когда курсор мыши оказывается над иконкой, а у элемента присутствует атрибут link, то форма курсора меняется, подсказывая, что по щелчку будет выполнен переход.
Графический элемент также поддерживает контекстное меню. Доступна опция для просмотра или редактирования атрибутов элемента, включая цвета, и опция удаления элемента.
Другие графические элементы
Почти все остальные элементы на графическом представлении кода могут иметь документацию (исключения, например, составляют комментарии и docstrings). Поэтому для них предусмотрен способ создания элемента документации через контекстное меню.
Контекстное меню для работы с документацией
Вариантов всего два. Первый «Add/edit doc link/anchor. » приводит к модальному диалогу для ручного ввода атрибутов link, anchor и title. Здесь у разработчика полная свобода куда направить ссылку, где разместить файл и т.п.
Второй вариант интереснее. Название пункта длинное, обусловленное выполняемыми действиями: «Create doc file, add link and open for editing». Все действия выполняются автоматически без всякого ввода, что позволяет решить организационный вопрос быстро:
а добавление документации осуществляется для файла проекта
то будет создан файл документации
Таким образом, структура документации к исходному коду повторяет структуру исходного кода, и даже быстрого просмотра подкаталога doc в проекте будет достаточно для интуитивно понятной навигации. Схема кажется разумной для поведения по умолчанию, что позволяет ускорить работу с документацией.
Стартовая точка документации проекта
Зачем нужна стартовая точка документации? По моему мнению она может облегчить процесс вхождения в проект для тех, кто впервые его открывает. Например, в случае расширения состава команды разработчиков, или для пользователей проекта. Представим себе, что у проекта есть документация и она состоит из большого количества файлов. С чего начать? Как документация структурирована? Вместо того, чтобы строить догадки и затем их проверять, удобнее было бы иметь явное указание рекомендованной точки входа.
Здесь можно немного расширить подход github так, чтобы работал и вариант по умолчанию, и вариант специфической организации документации. Если ничего не сказано, то будем искать файл README.md в корне проекта. А свойства проекта можно расширить еще одним полем, в котором указывается конкретный файл стартовой точки документации.
Для открытия документации проекта предусмотрено два варианта. На панели инструментов главного окна IDE добавлена кнопка с иконкой markdown. При нажатии будет открыт файл документации в режиме просмотра, если он имеется. Если же файла нет, то будет предложено расположение файла документации и будет открыта новая вкладка в режиме редактирования с текстом — заглушкой. Второй вариант — это ссылка на welcome страничке Codimension, которая показывется когда нет ни одной другой открытой вкладки. Сопроводительный текст будет включать слова о документации проекта и ссылку, если документация найдена. Именно эту welcome страничку увидет пользователь, открывший проект впервые.
Проверка на практике
Описанная выше функциональность опробована на кошках, то есть на проекте самой Codimension IDE. Теперь установочный пакет включает документацию, подготовленную в формате markdown. Это тестирование функциональности нельзя считать совсем полным, так как готовилась документация для конечного пользователя, а не по коду. Однако общее впечатление, что получилось вполне приемлимо.
Открытые вопросы
Нужна ли поддержка боковых CML doc элементов? Если да, то как их отрисовывать, например, для такого случая:
Можно было бы распознавать описания plantUML диаграмм прямо в строках документации. Если такая поддержка сделана, то как на графическом представлении кода показывать эти диаграммы?
Для облегчения построения plantUML диаграмм можно было бы добавить функциональность с таким сценарием:
Если у вас возникли идеи, пожалуйста, поделитесь ими в комментариях.
Учимся писать строки документации в Python
May 28, 2020 · 4 min read
Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.
Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.
Мы объединили наиболее часто употребляемые стили документирования в этой статье и остановились на Sphinx для дальнейшей разработки. Стиль Sphinx является официальным стандартом документации Python, и мы ценим его за простоту использования.
М ы надеемся, что эта статья даст вам общее представление о стилях и применениях строк документации, что станет хорошей основой для формирования опрятной документации в вашем коде Python.
Что такое докстринг?
Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками «»» «»» в начале модуля, класса, метода или функции, который описывает, что делает функция.
Лучшие практики
Однострочные докстринги
Многострочные докстринги
Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.
Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.
Стиль Sphinx
Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter.
Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:
Синтаксис Sphinx
Макет Sphynx
Общий макет этой строки документации показан ниже.
Эти стили документирования очень просты в применении, машиночитаемы для встроенных функций, интегрированных сред разработки и строк кода, а также являются единственным способом предоставить отлично документированные и читаемые функции для программистов. Их можно понять даже спустя несколько месяцев.
PEP 257 на русском. (Соглашение о Docstrings)
Аннотация
Данный PEP документирует семантику и соглашения, связанные с использованием Python docstrings.
Обоснование
«Общепринятые соглашения обеспечивают ясность, логичность, удобство сопровождения и воспитывают хорошие программистские привычки. Но они не заставляет вас действовать против своей воли. Это Python!»
Тим Питерс на comp.lang.python, 2001-06-16
Если вы избегаете общепринятых соглашений, в худшем случае на вас посмотрят искоса. Но существуют некоторые приложения (Например, системы документирования, подобные Docutils), которые позволят вам добиться более качественного результата, если вы знаете о договорённостях и будете им следовать.
Спецификация
Что такое Docstring?
Документационная строка — это строковый литерал, являющийся первой инструкцией в определении модуля, функции, класса или метода. Такая строка становится доступна при обращении с специальному атрибуту __doc__ этого объекта.
Все библиотеки, а также функции и классы, экспортируемые ими, должны иметь docstring. Публичные методы (включая конструктор __ init__) также должны иметь документацию. Сам же пакет может быть задокументирован внутри файла __init__.py, находящегося в соответствующей ему директории.
Строковые литералы, встречающиеся в других местах кода, также могут играть роль документации. Они не распознаются Python компилятором байт-кода и недоступны в качестве атрибутов объекта во время выполнения программы (т. е. у них отсутствует информация в __ doc__ ). Но существуют два дополнительных типа документационных строк, которые извлекаются с помощью других программных средств:
Для согласованности всегда используйте «»»тройные двойные кавычки»»» вокруг документационной строки. Если вы используете символы обратной косой черты («\»), то воспользуйтесь r»»»сырая строка с двойными кавычками»»» в ваших документациях. Для docstring, содержащих Unicode символы, используйте u»»»Юникод строка в тройных двойных кавычках»»». [прим. unicode строки потеряли смысл в python 3.x]
Существует две формы docstring: однострочные и многострочный.
Однострочные документационные строки
Однострочные строки используются для очевидных случаев и они должны действительно находится на одной строке. Например:
Значение фразы «командный тон» в английском языке можно пояснить на примере словосочетаний «Return pathname» и «Returns pathname». PEP-257 просит придерживаться первого стиля, потому что он более строгий.
Этот вид документаций подходит только для функций, написанных на языке C (таких как встроенные), где самоанализ невозможен. Также стоит упомянуть о природе возвращаемого значения. Предпочтительной формой для такой документационной строки будет что-то вроде:
(И конечно-же, «Сделай X» дожно быть заменено полезным описанием!)
Да, я только что писал выше: «Документация не является простым описанием», но в оригинале Гвидо и Дэвид действительно используют одинаковое слово «description» в этих двух местах. Думаю, что не стоит слишком придираться к этому, ведь посыл и так ясен.
Многострочные документационные строки
Многострочные документации состоят из сводной строки (summary line) имеющей такую же структуру, как и однострочный docstring, после которой следует пустая линия, а затем более сложное описание. «Summary line» может быть использована средствами автоматического документирования; поэтому так важно располагать её на одной строке и после делать пропуск в одну линию. Сводная строка пишется сразу после открывающихся кавычек, но допускается сделать перенос и начать со следующей строки. [прим. после этого предложения я был счастлив, ведь находились люди, которые упорно пытались мне доказать, что делать перенос ни в коем случае нельзя 🙂 ] При этом, весь docstring должен иметь такой же отступ, как и открывающие кавычки первой строки (см. пример ниже).
Оставляйте пустую строку после всех документаций (однострочных или многострочных), которые используются в классе; вообще говоря, методы класса должны быть отделены друг от друга одной пустой линией, поэтому документационная строка класса также должна быть отделена этим способом от первого метода.
Документация скрипта (автономной программы) представляет из себя сообщение «о правильном использовании» и возможно будет напечатано, когда скрипт вызовется с неверными или отсутствующими аргументами (или же с опцией «-h», для получения «help»). Такая документационная строка должна описывать функционал и синтаксис параметров скрипта, а также переменные среды и используемые файлы. Данное сообщение может оказаться довольно сложным (мануал длиной в несколько полных экранов), но при этом оно должно быть удобным для новых пользователей, чтобы они смогли использовать команду правильно. Также мануал должен давать чёткое описание всех параметров и аргументов для более опытных пользователей.
Документация модуля должна обычно содержать список классов, исключений и функций (и любых других важных объектов), которые экспортируются при помощи библиотеки, а также однострочное пояснение для каждого из них. (Это резюме, как правило, даёт меньше деталей, чем summary line в docstring самого объекта). В документации пакета (т. е. docstring модуля в __init__.py ) следует также описать и перечислить модули и подпакеты, экспортируемые главным.
Документация функции или метода должна описывать их поведение, аргументы, возвращаемые значения, побочные эффекты, возникающие исключения и ограничения на то, когда они могут быть вызваны (если это вообще предусмотрено). Также необходимо указать необязательные аргументы. Должно быть уточнено, являются ли ключевые аргументы частью интерфейса.
Документация класса должна обобщать его поведение и перечислять открытые методы, а также переменные экземпляра. Если класс будет иметь подклассы с дополнительный интерфейсом, то этот интерфейс должен быть указан отдельно (но всё также в этой документации). Конструктор класса должен иметь свою отдельную документационную строку для метода __init__. Независимые (индивидуальные) методы должны иметь собственную документацию.
Если класс является потомком и его поведение в основном наследуется от основного класса, в его документации необходимо упомянуть об этом и описать возможные различия. Используйте глагол «override» («переопределить»), чтобы указать факт подмены метода и что вследствие этого метод суперкласса вызываться не будет. Используйте глагол «extends» («расширяет»), если метод подкласса вызывает метод суперкласса (в дополнение к его собственному поведению).
Не используйте соглашение Emacs об упоминании аргументов функций или методов в верхнем регистре. Python чувствителен к регистру, а имена аргументов могут порой использоваться при их передаче по ключам, поэтому документация должна содержать реальные имена переменных. Лучше всего перечислять каждый аргумент в отдельной строке. Например:
Если весь docstring не помещается в строку, вы можете вынести закрывающие кавычки на отдельную линию. Таким образом, можно будет использовать Emacs команду: fill-paragraph
Обработка Docstring
Инструменты обработки документационных строк должны удалять одинаковое количество отступов, равное минимальному отступу всех не пустых строк, начиная со второй. Любые отступы в первой строке документации несущественны и будут удалены. Относительный отступ более поздних строк в строке документа сохраняется. Пустые строки должны быть удалены из начала и конца строки документа.
Поскольку код гораздо точнее слов, здесь приведена реализация алгоритма:
По сравнению с оригинальным кодом, в python3 атрибут sys.maxint был переименован в sys.maxsize, поэтому в коде это сразу исправлено.
Документация в следующем примере содержит два символа новой строки и поэтому имеет длину равную трём. Первая и последняя строки пусты:
Таким образом, после обработки следующие документационные строки будут эквивалентны: