Навигация в документации Python. Трюки и советы.

Введение

Если программирование это сарай, то документация это ключ к нему. Это первая аналогия, которая всплывает у меня в голове, когда я слышу слово документация. И действительно, если человек сможет понять, а главное ориентироваться в документации, то такому человек не потребуются, ни гайды, ни туториалы.
Важность документации нельзя недооценить, особенно для python разработчиков. Хоть я и буду разбирать и приводить примеры документации для python, советы и приёмы по навигации и ориентировке актуальны для любого языка программирования.

Что такое docstring и типы документации на python?

Итак, сначала поймём как же документация в python работает. Какие есть типы документации, что такое docstring и почему pydoc это такая классная вещь.

Об атрибуте __doc__

Как известно, всё в питоне это объект, от строчки до супер нагруженного модуля. Так называемый docstring это атрибут __doc__, того самого вездесущего объекта.
Введите, и вы обязательно найдёте атрибут __doc__ 

print(dir(str))
А теперь 

print("".__doc__)
Тебе вёрнёт строчку описания класса str 

str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is 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'.

Типы документации для языка python

Теперь когда мы с тобой обновили свои знания об __doc__ атрибуте, давай разберёмся какая документация бывает для программистов языка python.
Она бывает
  • Встроенная в интерпритатор python, команда help.
  • Сгенерированная pydoc (как в терминале, так и для браузера)
  • Сгенерированная другими инструментами.
Теперь разберёмся по порядку.

Встроенная команда help

Это так называеммая buildin функция python. Достаточно полезная, если ты встретился с нужным, но пока ещё не знакомым модулем или функцией для себя. Работает путём чтения __doc__ атрибута, как самого объекта, так и всех его методов и атрибутов.

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

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

pydoc -b
С модулем pydoc можно работать и как с функцией help. Введя: 

pydoc str
Ты получишь всё ту же документацию что и при использовании команды help 

str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is 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'.

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

Они работают по тому же принципу, что и pydoc. С той только разницей, что добавляют дополнительный функционал для документации, а некоторые позволяют улучшать и расширять их функционал.
Вот лишь некоторые популярные из них.
pdoc3
Работает с markdown, numpydoc, Napoleon, doctests
Основные фичи:
  • Нет необходимости в настройке. Работает из коробки.
  • Генерирует документацию в виде обычных текстовых файлов, HTML или PDF
  • Встроенный веб сервер.
пример генератора pdoc3 1 пример генератора pdoc3 2 пример генератора pdoc3 3
Sphinx
Использует по умолчанию такой язык разметки как reStructuredText, может ещё работать с MyST языком разметки.
Основными фишками являются:
  • Возможность генерировать документацию в виде HTML, PDF, ePub, Texinfo, Обычные текстовые страницы.
  • Подсветка кода
  • Расширенная перелинковка
генератор sphinx aiogram генератор sphinx scrapy генератор sphinx requests
MkDoc
Использует markdown как язык разметки
Основными фишками являются:
  • Возможность хостить свою документации почти везде. От github страниц до обычных сайтов
  • Легко кастомизируемый
  • Много классных тем
генератор MkDoc openml

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

Полезные фишки для тех, кто постоянно работает в интерактивной оболочке языка python.

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

[Раскрыть] Шеврон 

help('modules')

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

[Раскрыть] Шеврон 

from keyword import kwlist
print(*kwlist, sep='\n')

Получение списка build-in ф-ий

[Раскрыть] Шеврон 

import buildins
print(*buildins.__dict__.keys(), sep='\n')

Получение аттрибутов и методов класса объекта класса или самого класса

[Раскрыть] Шеврон 

dir(int)

Как ориентироваться и пользоваться документацией по python

Теперь моя любимая часть, как же всё-таки ориентироваться по многотомной документации. Особенно когда ты видишь её впервые.

Google лучший друг

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

site:https://example.com intext:"text" keyword1 keyword2

Позволяет быстро найти необходимые разделы в документации Например. Мне нужно создать клавиатуру для телеграм бота, я использую aiogram.
Тогда наш поисковый запрос будет следующим 

site:https://docs.aiogram.dev/en/latest/ intext:"keyboard" build inline
Мы знаем что нам нужна клавиатура, и знаем что один из типов клавиатуры называется инлайн.
intext пример поискового запроса на примере aiogram
Переходим по первой же ссылке и видим что кроме inline клавиатуры есть некий builder и ещё replay клавиатура. Берём и изучаем ;)

site:https://example.com intext:"text" OR intitle:"alt_text"

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

site:https://docs.djangoproject.com/en/5.0/intext:"pants"
Мы получим
пустой результат google поиска
Но если дополним наш запрос 

site:https://docs.djangoproject.com/en/5.0/ intext:"pants" OR intitle:"Template"
Мы получим искомые страницы
пример запроса с ключевым словом OR

site:https://example.com intext:"text" AND intitle:"alt_text"

Ключевое слово AND позволяет учесть обе переменные. В общем логическое И.
Если взять всё тот же запрос и поменять OR на AND 

site:https://docs.djangoproject.com/en/5.0/ intext:"pants" AND intitle:"Template"
То мы опять ничего не получим.
пустой результат google поиска

Другие поисковые операторы. Полный список.

  • “search term” Для точного совпадения с поисковой фразой.
  • OR Вернёт результаты либо для одного, либо для двух поисковых фраз.
  • AND Вернёт результаты только для двух поисковых фраз.
  • - Удалит поисковую фразу из поиска
  • * Подстановочный знак. Будет соответствовать любому слову или фразе.
  • ( ) Группирует несколько поисковых фраз или операторов для контроля, того как поиска отображает результаты.
  • $ Поиск цен.
  • define: Отображает значение слова.
  • Cache: Возвращает самую последнюю версию веб-страницы.
  • filetype: Показывает только страницы определённого типа (PDF, DOCX, TXT, PPT, ...)
  • site: Ограничивает поиск одним сайтом.
  • related: Находит похожие сайты.
  • intitle: Находит страницы с определёнными словами в заголовке.
  • allintitle: Находит страницы в которых присутствуют все слова в заголовке.
  • inurl: Находит страницы в URL которых входит та или иная фраза/слово.
  • allinurl: Находит страницы в URL которых входит полностью, та или иная фраза/слово.
  • intext: Находит страницы в теле тексте которых, присутствуют определённые слова.
  • allintext: Находит страницы в теле тексте которых, присутствуют все определённые слова.
  • AROUND(X) Возвращает только те страницы количество вхождений слов/фраз которых ровно X.
  • weather: Ищет погоду в определённой локации.
  • stocks: Возвращает информацию об запасах.
  • map: Просмотр результатов на карте для поиска местоположения.
  • movie: Поиск кино.
  • in Конвертирует одну величину в другую. Валюта, единицы измерения
  • source: Поиск по Google News.

Автодополнение кода, подсказки в редакторе

Вторым по значимости и нужности после Google, является автодополнение кода и всплывающие подсказки для выбора необходимой функции или атрибута. Особенно хорошо, когда автодополнение показывает вышеупомянутые docstring.
Данная фишка есть в любом IDE.
vscode автодополнение Nvim автодополнение visual studio автодополнение

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

Третьим по значимости для программиста это идёт документация. И так как, каждая документация разная, то и подход к каждой должен быть индивидуальным. Я могу дать лишь общие рекомендации, которые подходят под любую документацию.
  • Ищите содержание. Оно поможет вам узнать структуру проекта, его масштаб.
  • Если вы нашли для себя нужную страницу, пользуйтесь поиском по странице CTRL+F. Так быстрее и проще найти нужную информацию.
  • В футере всегда есть что-нибудь интересное.
  • Сделайте шаг выше. Возможно рядом с документацией (или в ней), вы сможете найти небольшие гайды и туториалы. Они помогут начать.

Заключение

Нет, поймите меня правильно. Вся информация в любом случае берётся из документации. Но вопрос не в источнике необходимой информации, а в том как её найти.
Ни один генератор документации, каким бы навороченным он ни был, не сможет переплюнуть Google в плане поиска релевантной информации.
Ведь почему мы вообще ищем эту информацию? Потому что у нас есть проблема, проблема порождает вопрос. А кто лучше всего отвечает на вопросы, правильно, поисковики в общем и Google в частности.
В любой документации есть индекс, ссылки, таблица содержания контента, ключевые слова. Это всё хорошо и нужно. Но лучше поисковика пока никто ещё ничего не придумал.
Конечно ChatGPT, вещь мощная. Но у него есть один, для меня фатальный недостаток. Он даст один единственный ответ без указания источников, без альтернатив. Да и работает ChatGPT поверх Google и его огромной базы данных сайтов. Поэтому, вот моё слово. Google must have.
сердце
0
3 соединённые точки
0

Использованные термины

Релевантные вопросы