Навигация в документации 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 -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
- Встроенный веб сервер.
Sphinx
Использует по умолчанию такой язык разметки как reStructuredText, может ещё работать с MyST языком разметки.
Основными фишками являются:
- Возможность генерировать документацию в виде HTML, PDF, ePub, Texinfo, Обычные текстовые страницы.
- Подсветка кода
- Расширенная перелинковка
MkDoc
Использует markdown как язык разметки
Основными фишками являются:
- Возможность хостить свою документации почти везде. От github страниц до обычных сайтов
- Легко кастомизируемый
- Много классных тем
Полезные фишки при работе со встроенной документацией
Полезные фишки для тех, кто постоянно работает в интерактивной оболочке языка python.
Получение списка доступных модулей
[Раскрыть]
Получение списка ключевых слов
[Раскрыть]
Получение списка build-in ф-ий
[Раскрыть]
Получение аттрибутов и методов класса объекта класса или самого класса
[Раскрыть]
Как ориентироваться и пользоваться документацией по 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
Мы знаем что нам нужна клавиатура, и знаем что один из типов клавиатуры называется инлайн.
Переходим по первой же ссылке и видим что кроме inline клавиатуры есть некий builder и ещё
replay клавиатура. Берём и изучаем ;)
site:https://example.com intext:"text" OR intitle:"alt_text"
Ключевое слово OR позволяет перечислять возможные варианты для поиска.
Тем самым, если в тексте ничего не найдётся, то поисковик будет искать в заголовках страниц.
К примеру, если мы введём
site:https://docs.djangoproject.com/en/5.0/intext:"pants"
Мы получим
Но если дополним наш запрос
site:https://docs.djangoproject.com/en/5.0/ intext:"pants" OR intitle:"Template"
Мы получим искомые страницы
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"
То мы опять ничего не получим.
Другие поисковые операторы. Полный список.
- “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.
Поиск в документации на сайтах
Третьим по значимости для программиста это идёт документация.
И так как, каждая документация разная, то и подход к каждой должен быть
индивидуальным. Я могу дать лишь общие рекомендации, которые подходят
под любую документацию.
- Ищите содержание. Оно поможет вам узнать структуру проекта, его масштаб.
- Если вы нашли для себя нужную страницу, пользуйтесь поиском по странице CTRL+F. Так быстрее и проще найти нужную информацию.
- В футере всегда есть что-нибудь интересное.
- Сделайте шаг выше. Возможно рядом с документацией (или в ней), вы сможете найти небольшие гайды и туториалы. Они помогут начать.
Заключение
Нет, поймите меня правильно. Вся информация в любом случае берётся из документации.
Но вопрос не в источнике необходимой информации, а в том как её найти.
Ни один генератор документации, каким бы навороченным он ни был, не сможет переплюнуть Google
в плане поиска релевантной информации.
Ведь почему мы вообще ищем эту информацию? Потому что у нас есть проблема, проблема порождает вопрос.
А кто лучше всего отвечает на вопросы, правильно, поисковики в общем и Google в частности.
В любой документации
есть индекс, ссылки, таблица содержания контента, ключевые слова. Это всё хорошо и нужно. Но лучше поисковика пока
никто ещё ничего не придумал.
Конечно ChatGPT, вещь мощная. Но у него есть один, для меня фатальный недостаток. Он даст один единственный ответ
без указания источников, без альтернатив. Да и работает ChatGPT поверх Google и его огромной базы данных сайтов.
Поэтому, вот моё слово. Google must have.
0
0
