Навигация в документации 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.
Она бывает
Теперь разберёмся по порядку.

Встроенная команда 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 поиска

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

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

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

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

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

Заключение

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

сердце 0
3 соединённые точки 0

Коментарии

(0)
Аватар по умолчанию
None
Оставить комментарий
Оставить комментарий