как писать документацию к коду 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: поиск информации и соглашения

Python обладает великолепной документацией и предоставляет удобные способы для работы с ней: от официального сайта до встроенной справочной системы.

Работа с документацией является одной из важных составляющих деятельности разработчика. И это не только чтение документации к библиотекам и комментариев в коде, но и документирование собственного кода, а также поддержание его в актуальном состоянии. Качественно задокументированный код во многих случаях упрощает его поддержание и сокращает время на «вхождение» новых сотрудников в проект. Если же речь идет об изучении нового языка программирования, качество документации и поддержка сообщества могут сыграть решающую роль в освоении материала и снизить порог вхождения.

Документация к языку программирования Python обладает всеми качествами, которые отличают «хорошую» документацию от «плохой». Тем не менее, новички часто сталкиваются с рядом вопросов. Как быстро найти информацию о классе или функции? Как самому писать документацию к коду? Какие инструменты можно использовать при документировании кода? На эти вопросы мы и постараемся ответить в статье.

Основной источник информации о Python

Безусловно, основным, наиболее полным и актуальным источником информации о Python является сайт c официальной документацией. Главная страница сайта предоставляет удобную навигацию по разделам.

Важные разделы сайта (полезно начинающим программистам)

В остальных разделах вы можете найти информацию о сторонних модулях, их установке и распространении, информацию по написанию расширений для Python на языках С/С++, часто задаваемые вопросы и новости Python.

Поиск по сайту с документацией

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

Создатели Python предусмотрели возможность установить документацию локально на компьютере. Для этого необходимо перейти на страницу загрузки, выбрать версию Python, формат файлов (доступны pdf, epub, html, txt) и способ архивирования. После скачивания и распаковки архива, вы можете пользоваться документацией в полном объеме.

Встроенная справочная система

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

Небольшое уточнение: поскольку в Python все является объектом, в том числе методы и классы, далее мы будем часто употреблять термин «объект» применительно к целям получения информации.

Примеры

Почему вызов функции завершился выбросом исключения? Ведь модуль os входит в стандартную библиотеку и маловероятно, что справочная информация по нему не была включена.

Docstring

Посмотрим, что хранится в атрибуте __doc__ объекта ord.

Посмотрим на исходный код модуля os и убедимся в том, что docstring и содержимое атрибута os.__doc__ совпадают. Из приведенного кода видно, как определяются в коде docstring. Строки документации заключаются в тройные кавычки и пишутся сразу под заголовком объекта.

Вы уже заметили, что вывод функции help отличается от вывода, полученного через обращение к атрибуту __doc__ объекта. Он более информативен и выводит информацию в виде форматированного текста. У функции help есть еще одна особенность, повышающая удобство работы со справочной системой. При вызове help без аргументов запускается интерактивный режим справочной системы. Для получения справки в нем достаточно набрать только название интересующего нас объекта. Запустив интерактивный режим в отдельном терминале, мы получаем удобный инструмент для работы с документацией.

Как вспомнить название модуля, класса или функции?

Стандартная библиотека Python весьма обширна и содержит большое количество модулей. Помнить их все, в том числе и заложенный функционал, невозможно. Что делать, если мы не помним (не знаем) название модуля, класса или функции? Ниже приведены несколько примеров, помогающих в таких ситуациях.

Получение списка доступных модулей:

Получение ключевых слов:

Получение списка названий встроенных функций:

Как задокументировать собственный код?

Убедимся в наличии документации по модулю factorial :

Вызов help(factorial) вернет справку:

При создании документации к коду стоит придерживаться правил и рекомендаций, описанных в PEP257 и PEP8. Ссылки на эти документы приведены в конце статьи.

О библиотеке pydoc

Команда pydoc позволяет вывести текст справки прямо в терминале (не интерпретаторе Python):

Соблюдение соглашений

Модуль pydocstyle — это инструмент статического анализа для проверки соответствия docstring соглашениям, принятым в Python. Установка модуля осуществляется с помощью менеджера пакетов pip:

По умолчанию pydocstyle проверяет docstring на соответствие официальному соглашению PEP257. Проверим созданный нами скрипт factorial.py:

Видим, что pydocstyle обнаружил ошибки — лишние пробелы вокруг текста и отсутствие точки в конце строк документации. Исправим эти ошибки и запустим pydocstyle еще раз.

Источник

Учимся писать строки документации в Python

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

Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.

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

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

Что такое докстринг?

Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками «»» «»» в начале модуля, класса, метода или функции, который описывает, что делает функция.

Лучшие практики

Однострочные докстринги

Многострочные докстринги

Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.

Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.

Стиль Sphinx

Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter.

Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:

Синтаксис Sphinx

Макет Sphynx

Общий макет этой строки документации показан ниже.

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

Источник

Составление документации для проектов на Python

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

1. Чистый и информативный код

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

2. Строки документации, комментарии и сообщения коммитов в Git

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

Что касается синтаксиса, строки документации берутся в тройные кавычки и могут быть как однострочными, так и многострочными. Комментарии же начинаются с символа # в начале.

Есть много доступных форматов строк документации. Чаще всего используются docstring-стили NumPy, PyDoc и Googles. Рекомендуется придерживаться формата, который поддерживает генератор документации Python Sphinx. Он автоматически генерирует часть вашей документации прямо из ваших docstrings, что очень удобно. В последнем разделе нашей статьи мы покажем, как создавать и размещать документацию с помощью Sphinx и readthedocs.

Для облегчения создания строк документации есть удобное расширение VS Code — Python Docstring Generator.

Это расширение автоматически определяет параметры, вам нужно лишь заполнить отмеченные поля. По умолчанию используется стиль Google.

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

Если вы используете VS Code, вы можете также расширить возможности Git с помощью GitLens. Благодаря этому расширению вы будете видеть сообщения коммитов рядом с кодом, вошедшим в этим коммиты.

Есть еще один полезный инструмент — gitmoji. С его помощью можно добавить эмодзи в сообщения коммитов, что сделает их более читабельными. Кроме того, он мотивирует коммитить только те изменения кода, которые попадают в одну из категорий gitmoji.

Марк Лутц «Изучаем Python»

Скачивайте книгу у нас в телеграм

3. README-файлы

Красиво написанный README — это первый документ, который увидит посетитель проекта.

Каким должен быть хороший README, что он должен содержать?

Часто файлы README также содержат инструкции по установке приложения или руководство по его использованию.

4. Sphinx-документация

Для небольших проектов может быть достаточно README.md. Тем не менее, такие проекты, как библиотеки, нуждаются в намного более обширной технической документации. Сейчас мы покажем вам, как просто создать свою собственную бесплатную документацию с помощью Sphinx, readthedocs и Github Pages!

Итак, давайте создадим документацию! Sphinx — это инструмент, который поможет нам упростить этот процесс.

Sphinx задаст нам пару вопросов:

Для создания документации нужно использовать команду make html в каталоге docs. Это создаст HTML-код нашей документации.

Если мы откроем файл index.html в браузере (при помощи live server), мы увидим, как он будет выглядеть. Но его внешний вид пока довольно скучный. Поэтому, чтобы придать файлу профессиональный вид, мы используем популярную тему RTD. Давайте установим тему:

Теперь настроим файл conf.py. Добавляем следующие строки:

А теперь запустим всё снова:

Последний шаг – опубликовать нашу документацию. Для этого нужно зарегистрироваться на readthedocs.org и подключить его к нашему репозиторию.

Вуаля! Создана хорошая документация! (Результат можно посмотреть здесь). Мы надеемся, вы поняли, как писать грамотную документацию, а также — как просто и красиво её оформить.

Источник

Как сделать документацию к функции?

1 ответ 1

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

Давайте сделаем небольшую функцию:

Функция есть, давайте сделаем к ней описание для тех, кто будет, например, импортировать модуль с ней.

Теперь вызовем нашу документацию:

Документацию можно вызвать и с помощью команды help(), но тогда свернётся весь наш аутпут и откроется что-то типа подокна (если вы знакомы с редактором nano, то вам будет проще понять), из которого можно выйти, нажав q

Почему не вызывем документацию у to_str_smth(), указывая скобки? Потому что так функция затребует аргументы, если они обязательны. К тому же, таким образом мы можем вернуть документацию подфункции, если она указана в return.

Посмотрим, например, на эту функцию:

Давайте попробуем вывести на экран документацию для неё, указав скобки:

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

Не совсем то, что хотелось бы видеть.

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

Если мы хотим сохранить документацию, сделать это можно с помощью программы, которая идёт в комплекте с Python под названием pydoc. Для каждой версии есть свой pydoc, так что убедитесь, что вы запускаете ту версию pydoc’а, иначе может возникнуть конфликт импорта модулей.

Сделать это можно следующим образом (подразумевается, что запуск идёт из директории с модулем):

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

Источник