Это часть 7 многоуровневой серии «Эволюция сценария». Кодекс этого поста можно найти на GitHub (см. Здесь ).
- Чистый и самоописательный код
- Комментарии, Docstrings и GIT Commit Commit сообщений
- Readme файлы
- Документация сфинкса
В этом посте я хочу поговорить о нескольких измерениях того, как документировать проект в мире Python. Это облегчает пользователю или других разработчикам понять проект в целом или отдельных частях этого. Мы начнем на самом низком уровне и движемся к более высоким уровням абстракции.
Самый низкий уровень документации является сам код. Цель состоит в том, чтобы создать читаемое и многоразовое программное обеспечение. Это может быть достигнуто путем соблюдения нескольких принципов:
- Значительный, произносимый и последовательный Наименование переменных/функций/классов.
- Односсионный принцип : Каждая функция выполняет только 1 цель, одинаково относится к классам/модулям на более высоком уровне абстракции.
- Использовать Статическое печатать Для более крупных проектов, принудительный тип проверки с Marpy Отказ Динамические языки, такие как Python, затрудняет идентификацию объекта.
- Избегайте переосмысления колеса и используйте хорошее использование Стандартная библиотека Python Отказ Хороший разработчик использует существующий код стратегически для его преимущества.
- Придерживайтесь последовательного стиля, мне нравится Goggles стиль гида для питона.
- Код элегантный и приятный? Послушайте свою интуицию Ваш подсознание будет указывать на правильные вещи.
>>> import math >>> math.__doc__ 'This module is always available. It provides access to the' 'mathematical functions defined by the C standard.'
DocStrings – это строковые литералы, которые происходят в качестве первого утверждения в функции, классе, методе или определении модуля. Docstrings становятся __doc__ Специальный атрибут этого объекта. Они используются для объяснения общего назначения объекта, тогда как комментарии объясняют меньшие части кода. Комментарии используются для объяснения неочевидных порций кода. Docstrings окружены «« Тройные цитаты »" "" и разделен на однострочные или многострочные документы, в то время как комментарии начинаются с # с начала.
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 Docsstring Style. Это хорошая идея, чтобы придерживаться формата, который поддерживает генератор документации Python Сфинкс . Это автоматически генерирует часть вашей документации с ваших DocStrings. Последний раздел этого поста покажет, как генерировать и проводить документацию с помощью SPHINX и ReadTheDocs. .
Удобное расширение VSCode является Генератор Python DocString облегчить создание Docstrings.
def multiply(x: int, y: int) -> int:
"""[summary]
Args:
x (int): [description]
y (int): [description]
Returns:
int: [description]
"""
return x * y
Он автоматически обнаруживает параметры, и вам просто нужно заполнить отмеченные поля. Он использует стиль Google по умолчанию.
Другой источник документации доступен, если проект имеет историю Git. Хорошая история GIT дает вам информацию о причине каждого изменения кода. Вы можете перезарядить возможности GIT VSCode by Gitlens И вы увидите каждое сообщение COMBING рядом с кодом, на который он был привержен.
Кроме того, я люблю использовать Gitmoji Чтобы сделать чтение моих сообщений Commit Visual более привлекательным и заставить себя совершать только изменения кода, которые попадают в одну категорию GitMojis.
Хорошо написанный Readme является первым документом, который увидит посетитель проекта. Вот скриншот САЛОН IRC-клиент для самообедания:
Какая красивая Readme! Что это делает так хорошо?
- Это имеет визуально привлекательный и запоминающийся логотип который совместим с легкой и темной темой GitHub, используя прозрачный
.pngрисунок. - А Краткое саморегулирование Отказ
- Значки от Shields.io которые визуализируют качество проекта.
- Ссылки на Документация Отказ
- Пример Здесь скриншот приложения при запуске.
- А Список содержащийся Особенности Отказ
Часто файлы Readme также содержат инструкции для установки или учебника о том, как его использовать. Формат файла readmes – .md.md (Реклама) или .rst.rst (реструктурный текст). Иногда также хорошая идея предоставить примеры пользователю для определенных случаев общего использования. Проекты с научным фоном данных, как правило, используют ноутбуки Jupyter ( .ipynb ), чтобы продемонстрировать возможности проекта. Другие проекты используют обычные файлы Python для демонстрационных целей.
Для меньших проектов Readme.md Может быть достаточно, тогда как проекты, такие как библиотеки, получают выгоду от более широкой технической документации. Я покажу вам здесь, как просто создать свою собственную свободно размещенную документацию с Сфинкс , ReadTheDocs. и Страницы GitHub Действительно
Хорошо, давайте создадим некоторую документацию! Сфинкс Является ли инструмент, который поможет нам упростить этот процесс.
$ pip install sphinx $ mkdir docs $ cd docs
Сфинкс спросит нас пару вопросов:
$ 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
Чтобы создать документацию, мы должны использовать сделать HTML Команда внутри документы каталог. Это создает 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
Теперь это выглядит лучше! Да дальше мы хочем написать еще более контент. Документация должна быть написана в синтаксисе реструктурированного текста (.rst). Вот хороший чит лист Отказ А .rst.rst Предварительный просмотр в вашем IDE будет ускорить вещи. Я добавил некоторую документацию о Tinyhttpie, см. index.rst , install.rst и Tutorial.rst Отказ Последний шаг – публиковать нашу документацию. Мы должны зарегистрироваться на readthedocs.org И позвольте ему крюкнуть наш репозиторий.
Вуаля! Хороший Документация был создан! Я надеюсь, что вы видите, как легко настроить такую красивую документацию, и эта документация имеет так много интересных аспектов, о которых мы обычно не знаем! 😃
Оригинал: “https://dev.to/niklastiede/writing-documentation-for-python-apps-44d8”