В этой статье мы бы хотели поговорить о том, как писать грамотную документацию в мире Python. Хорошая документация облегчает пользователю и другим разработчикам понимание как проекта в целом, так и отдельных его частей. Мы начнем с базовых вещей и постепенно будем переходить к более глубоким тонкостям.
1. Чистый и информативный код
Самая базовая вещь в документации — это сам код. Цель состоит в том, чтобы создать читаемое программное обеспечение, пригодное для повторного использования. Этого можно добиться, придерживаясь нескольких принципов:
- Имена переменных, функций и классов должны быть осмысленными, удобопроизносимыми и последовательными.
- Придерживайтесь принципа единственной ответственности. Он заключается в том, что каждая функция выполняет только одну задачу (то же самое относится к классам и модулям).
- Используйте статическую типизацию для больших проектов. Динамические языки, такие как Python, делают идентификацию объектов более сложной.
- Не изобретайте велосипед 🙂 Эффективно используйте стандартные библиотеки Python. Ведь хороший разработчик всегда использует существующий код в своих интересах.
- Придерживайтесь единого стиля.
- Прислушивайтесь к своей интуиции, делая код элегантным и приятным.
2. Строки документации, комментарии и сообщения коммитов в Git
>>> import math >>> math.__doc__ 'This module is always available. It provides access to the' 'mathematical functions defined by the C standard.'
Строки документации (docstrings) — это строковые литералы, которые встречаются в качестве первых предложений при определении функции, класса, метода или модуля. Они становятся специальным атрибутом этого объекта — __doc__.
Строки документации используются для объяснения общего назначения объекта, в отличие от комментариев, объясняющих более мелкие и неочевидные части кода.
Что касается синтаксиса, строки документации берутся в тройные кавычки и могут быть как однострочными, так и многострочными. Комментарии же начинаются с символа # в начале.
def my_function():
"""This is a docstring"""
return None
# docstring of the function
my_function.__doc__
# displays documentation of the function
help(my_function)
Есть много доступных форматов строк документации. Чаще всего используются docstring-стили NumPy, PyDoc и Googles. Рекомендуется придерживаться формата, который поддерживает генератор документации Python Sphinx. Он автоматически генерирует часть вашей документации прямо из ваших docstrings, что очень удобно. В последнем разделе нашей статьи мы покажем, как создавать и размещать документацию с помощью Sphinx и readthedocs.
Для облегчения создания строк документации есть удобное расширение VS Code — Python Docstring Generator.
def multiply(x: int, y: int) -> int:
"""[summary]
Args:
x (int): [description]
y (int): [description]
Returns:
int: [description]
"""
return x * y
Это расширение автоматически определяет параметры, вам нужно лишь заполнить отмеченные поля. По умолчанию используется стиль Google.
Для проектов, имеющих историю Git, есть еще один источник документации. Дело в том, что хорошая история Git дает вам информацию о причине каждого изменения кода.
Если вы используете VS Code, вы можете также расширить возможности Git с помощью GitLens. Благодаря этому расширению вы будете видеть сообщения коммитов рядом с кодом, вошедшим в этим коммиты.
Есть еще один полезный инструмент — gitmoji. С его помощью можно добавить эмодзи в сообщения коммитов, что сделает их более читабельными. Кроме того, он мотивирует коммитить только те изменения кода, которые попадают в одну из категорий gitmoji.
[python_ad_block]3. README-файлы
Красиво написанный README — это первый документ, который увидит посетитель проекта.
Каким должен быть хороший README, что он должен содержать?
- Файл README должен иметь визуально привлекательный и запоминающийся логотип. Этот логотип должен быть совместим и со светлой, и с темной темой GitHub. Для этого нужно использовать изображение с прозрачным фоном, в формате
.png. - В файле должно быть краткое описание проекта и список имеющихся функций.
- Значки от shields.io помогут визуализировать качество проекта.
- Юудет полезным добавить ссылки на документацию, примеры и скриншоты (например, скриншот приложения при запуске).
Часто файлы README также содержат инструкции по установке приложения или руководство по его использованию.
Файлы README обычно имеют расширения .md(markdown) или .rst (reStructuredText).
Хорошей практикой считается предоставление пользователю примеров распространенных вариантов использования программы. В проектах, имеющих отношение к data science, для демонстрации возможностей проекта обычно используются блокноты jupyter (.ipynb). В других проектах в демонстрационных целях используются простые файлы Python.
4. Sphinx-документация
Для небольших проектов может быть достаточно README.md. Тем не менее, такие проекты, как библиотеки, нуждаются в намного более обширной технической документации. Сейчас мы покажем вам, как просто создать свою собственную бесплатную документацию с помощью Sphinx, readthedocs и Github Pages!
Итак, давайте создадим документацию! Sphinx — это инструмент, который поможет нам упростить этот процесс.
$ pip install sphinx $ mkdir docs $ cd docs
Sphinx задаст нам пару вопросов:
$ sphinx-quickstart > Separate source and build directories (y/n) [n]: y > Project name: tinyHTTPie > Author name(s): Niklas Tiede > Project release []: 0.1.0 > Project language [en]: enter
Для создания документации нужно использовать команду make html в каталоге docs. Это создаст HTML-код нашей документации.
$ cd .. $ make html
Если мы откроем файл index.html в браузере (при помощи live server), мы увидим, как он будет выглядеть. Но его внешний вид пока довольно скучный. Поэтому, чтобы придать файлу профессиональный вид, мы используем популярную тему RTD. Давайте установим тему:
$ pip install sphinx_rtd_theme
Теперь настроим файл conf.py. Добавляем следующие строки:
import sphinx_rtd_theme extensions = ["sphinx_rtd_theme",] pygments_style = "sphinx" version = '0.1.0' html_theme = 'sphinx_rtd_theme'
А теперь запустим всё снова:
$ make html
Теперь всё выглядит намного лучше! Только нужно добавить немного контента. Документация должна быть написана в синтаксисе reStructuredText(.rst). Здесь вы можете найти хорошую шпаргалку. Кроме того, предварительный просмотр .rst в вашей IDE значительно ускорит работу.
Последний шаг – опубликовать нашу документацию. Для этого нужно зарегистрироваться на readthedocs.org и подключить его к нашему репозиторию.
Вуаля! Создана хорошая документация! (Результат можно посмотреть здесь). Мы надеемся, вы поняли, как писать грамотную документацию, а также — как просто и красиво её оформить.
