Мой мадригал тем инструментам разработки, которые изменили мою жизнь
Программирование: срез за много лет
Программирование стало гораздо более многогранным ремеслом с тех пор, как в середине 1990-х я впервые попробовал AmigaBASIC. В те времена еще можно было купить один большой том о компьютере, на котором вы программируете – и там бы нашлось 99% всей нужной информации. Эта книга, где на множестве страниц уголки загнуты в качестве закладок, обклеенная стикерами, лежала бы у вас под рукой, пока вы вбивали бы команды в монохромный текстовый редактор.
Современная книга по клиентскому веб-фреймворку может быть толще, чем во времена программирования под C64 бывали мануалы, достаточные для создания полноценных игр. С другой стороны, сегодня информация по любым платформам, для которых требуется писать код, находится буквально в одном клике.
Сегодня никто бы больше и не подумал покупать документацию по разработке – и Microsoft, и Apple свободно выкладывают свою документацию в Интернете для всех желающих. А что говорить о проектах с открытым исходным кодом!
Во времена npm, PyPI и GitHub сложно объяснить, насколько неоднозначным решением (которое требовалось всесторонне обдумывать) раньше считалось потребовать хоть какие-нибудь возможности, которые выходили бы за рамки функционала операционной системы. Часто вместе с продуктом приходилось сдавать и все его зависимости.
Нынешнее изобилие и разнообразие инструментов – это благо, но в таких условиях фрагментируется информация, необходимая вам для продуктивной работы.
У вас могут быть открыты десятки вкладок с документацией по пакетам, с которыми вы работаете в настоящий момент. Вы бешено перещелкиваете вкладки, чтобы найти нужную. Поскольку мне доводилось работать из лучшего в мире города для занятий лонгбордингом, где несколько десятков тысяч человек делят одну точку присутствия на всех, могу вас заверить, что чисто онлайновые документы – не единственная проблема, когда Интернет намертво отрубается. Скажу вам, что поиск при сбоящем Интернете – это хуже, чем вообще никакого поиска.
Если вы, как и я, работаете сразу со множеством языков программирования, вокруг каждого из которых сформировались колоссальные субкультуры (даже в пределах Python есть Flask + SQLAlchemy + Postgres, которая кардинально отличается от программирования сетевых серверов на основе asyncio), то поймете, что мне просто дурно помыслить, может ли кто-нибудь вспомнить все аргументы к каждому из используемых мной методов. В основном потому, что я сам едва вспоминаю собственный номер телефона.
Вот почему моя жизнь в корне изменилась в 2012 году, когда я открыл для себя Dash.
Обозреватели документации по API
Разум нужен, чтобы придумывать идеи, а не хранить их.
— Дэвид Аллен
![Поиск в Dash Поиск в Dash](https://habrastorage.org/getpro/habr/upload_files/74e/f3b/b87/74ef3bb87d7053ddcb03b828375fd5e2.png)
Dash наделяет меня суперсилой – иметь все актуальные API под рукой, только один раз на клавишу нажать:
Нажимаю «Пробел» - и всплывает окно со строкой поиска, в которой уже стоит курсор,
Начинаю вводить приблизительное название API или темы
Выбираю из предложенных вариантов – и выхожу на символ, по которому открывается официальная документация к проекту.
Нажимаю Esc – и всплывающее окно исчезает, а я могу сразу снова писать код, потому что мой редактор снова в фокусе.
Если я забуду, о чем только что читал – то просто вновь нажимаю «Пробел» - и окно всплывает в том же месте, где находилось ранее.
Все это происходит молниеносно – я хочу, чтобы на путь в оба конца уходило менее 2 секунд. Такая скорость и нужна, чтобы не терять концентрацию и не забывать, чем занимаешься. Я уже научился делать все это на автомате. Давно забытая роскошь нативных приложений – да, я знаю о https://devdocs.io.
Когда вся документация по API лежит на расстоянии одного клика – какую силу тебе это придаёт!
Чем меньше сил я трачу на припоминание аргумента функции или на то, чтобы вспомнить путь, по которому будет импортироваться класс – тем больше могу сосредоточиться на обдумывании решаемой задачи.
Не считаю себя особенно умным, поэтому не упускаю возможности разгрузить мозг.
Притом, что приложение Dash для Mac стоит $ 30 Mac (также доступно в рамках подписки Setapp!), имеются бесплатные аналоги под Windows и под Linux, называются Zeal, а также приложение за $ 20 под Windows, называется Velocity. Естественно, существует как минимум один пакет Emacs для той же цели: helm-dash.
Мораль: такую благодать с API можно организовать на любой платформе! Далее я напишу конкретно о Dash, поскольку работаю именно с ним, но, если не указано иное, то все сказанное применимо к любым инструментам.
Одна штука, общая для всех этих инструментов – общий формат для создания локальной документации.
Наборы документации
Все они используют пакеты с наборами документации (docsets) от Apple – это каталоги с документацией в формате HTML, метаданные в списке свойств, основанном на формате XML, а также индекс для поиска в базе данных SQLite:
some.docset
└── Contents
├── Info.plist # ← метаданные
└── Resources
├── Documents # ← корневой каталог с HTML-документами
│ └── index.html
└── docSet.dsidx # ← База данных SQLite с поисковым индексом
Если у вас на диске есть куча HTML-файлов, то их можно преобразовать в набор docset, который уже может потребляться Dash. Это просто HTML-файлы с метаданными. А поскольку эти HTML-файлы лежат у вас на диске, все работает оффлайн.
Следовательно, наборы docsets могут заменить документацию, которые вы и так держите на локальном компьютере, чтобы иметь к информации быстрый и/или оффлайновый доступ, ничего особенного не делая. Просто упакуйте этот материал в нужную структуру каталогов, добавьте пустой индекс и внесите простые метаданные.
Сезам! Теперь их можно поднять, нажав всего одну клавишу, а убрать их с глаз другой клавишей.
Давайте вернемся к тому скучному историческому экскурсу, с которого начиналась эта статья: я работаю с мириадами проектов на бесчисленных платформах, изо дня в день. Причем, я в данном случае имею в виду не только API для программирования, а еще и роли Ansible, классы CSS, конфигурацию HAProxy, тонкости Postgres (и SQL!)…много всего.
![Установленные наборы Dash docsets Установленные наборы Dash docsets](https://habrastorage.org/getpro/habr/upload_files/d6e/806/0ee/d6e8060eeb0a91102d36143da49c9f82.png)
Хотя базовая документация по Python и Go поставляется с Dash, а документацию Godoc можно добавить прямо по URL, но, как бы Dash ни старался – все тщетно. Современный мир разработки ПО настолько фрагментирован, что ни один инструмент не предоставит мне всего, что мне нужно.
Sphinx
Серьезнейшим недостающим звеном для меня стали документы на основе Sphinx, доминирующие во всей экосистеме Python (и не только в ней).
Sphinx – это фреймворк для написания документации, от конкретного языка он не зависит. Это не просто документация по API, равно как и не повествовательные документы, а все сразу, причем, сильно перелинкованное. Sphinx в свое время снискал дурную славу, так как вынуждал пользователей работать с reStructuredText, но теперь становится все больше таких проектов, которые опираются на чудесный пакет MyST, позволяющий все сделать в Markdown. Если у вас есть какие-либо предубеждения по поводу того, как выглядит документация Sphinx, настоятельно рекомендую посетить галерею с темами Sphinx и посмотреть, насколько красивы могут быть ваши документы. Инструмент написан на Python, но используется широко, в том числе, в ядре Linux, в Swift от Apple, в проекте LLVM (Clang!) или в бешено популярных PHP-проектах.
Кроме того, он предлагает то самое недостающее звено: индекс записей API, разделов, терминов из глоссария, конфигурационных опций, аргументов командной строки и пр. Все это распределяется по вашей документации таким образом, как вам угодно, но всегда поддается перелинковке, туда и обратно. Я считаю, это просто чудесно, особенно, если вы придерживаетесь систематического фреймворка, например, Diátaxis.
Ключевой компонент, обеспечивающий все это, строго говоря – просто расширение: intersphinx. Исходно он создавался для внутрипроектной перелинковки (отсюда и название) и предлагает к нашим услугам машинно-читаемый индекс. Этот индекс стал настолько популярен, что сейчас даже поддерживается через специальное расширение для MkDocs под названием mkdocstrings и через pydoctor. Документация, совместимая с intersphinx, узнается именно по такому файлу индекса: objects.inv
.
Именно поэтому я 10 лет назад начал и до сих пор веду проект doc2dash.
doc2dash
Это инструмент командной строки, который можно скачать у меня на Homebrew tap, скачать один из заранее подготовленных бинарников для Linux, macOS и Windows со страницы с релизами или установить из PyPI.
Затем, все, что вам останется сделать – это указать данному инструменту путь к каталогу с intersphinx-совместимой документацией, и он сделает все нужное, чтобы предоставить вам docset.
![Преобразование doc2dash Преобразование doc2dash](https://habrastorage.org/getpro/habr/upload_files/da7/f65/fdc/da7f65fdc1bc8cabf0d147d9fd554301.png)
Обратите внимание: имя здесь doc2dash, а не sphinx2dash. Инструмент всегда позиционировался как фреймворк для написания высококачественных конвертеров, и первые в их ряду — Sphinx и pydoctor. К сожалению, этой надежде было не суждено сбыться, так как – что логично – в каждом сообществе предпочитали работать со своим языком и собственным инструментарием.
Но мне эти инструменты всегда казались какими-то одноразовыми, поэтому лишний раз подчеркну, что мне хотелось бы работать с другими инструментами, обеспечивающими поддержку для других форматов документации. Не нужно изобретать велосипед, весь фреймворк уже готов! Это просто файл с кодом! Вам даже не требуется открывать ваш парсер ни мне, ни всему миру.
Сам факт, что и Dash, и doc2dash уже давно разменяли второй десяток, а среди моих друзей по-прежнему есть ребята, у которых при работе открыт дохреллион вкладок с API-документацией. У меня от этого сердце сжимается, в хорошем смысле. Продолжаю показывать людям, как работает Dash, настаиваю, что он крут, и они заносят его в свои списки «когда-нибудь разберусь». Но без лишних напоминаний это «когда-нибудь» так и не наступает.
На этом заканчивается вводная часть статьи (про память как у золотой рыбки), и я попробую вас растормошить, чтобы это «когда-нибудь» наступило «сегодня»!
Учимся преобразовывать и отправлять документацию
Цель этого руководства – научить вас преобразовывать intersphinx-совместимую документацию в docset и как отправлять полученный результат в генерируемый пользователем реестр docset, поддерживаемый в Dash – так, чтобы другим не требовалось дублировать уже проделанную вами работу.
Исходим из того, что вы уже выбрали и установили ваш любимый обозреватель API. Не важно, какой именно вы используете, но в данном руководстве вся работа рассмотрена на примере Dash. Если вы хотите опционально отправлять docset по результатам работы, то вам также потребуется базовое понимание GitHub – в частности, нужно знать, как в нем построена работа с пул-реквестами.
Когда я взялся работать над этим руководством, мне наконец-то представился случай приступить к публикации docsets по моим собственным проектам, начиная со structlog. Предлагаю вам самим подобрать проект, совместимый с intersphinx, который пока не поддерживается в Dash, и вкладку с документацией по которому вы открываете чаще всего.
Приступим же!
Обзаводимся doc2dash
Если вы уже пользуетесь Homebrew, то проще всего взять doc2dash прямо у меня, отсюда:
$ brew install hynek/tap/doc2dash
Там есть заготовленные бутылки для Linux x86-64 и macOS как на x86-64, так и на Apple silicon, поэтому установка должна пойти очень быстро.
Если вы сами не придумали обходной маневр, помогающий оптимизировать установку пакетов Python, то лучше всего воспользоваться заранее собранными бинарниками со страницы релизов. В настоящее время предлагаются бинарники для Linux, Windows и macOS – все для архитектур x86-64. Надеюсь, в будущем появятся и другие предложения, если этот подход окажется популярным. Наконец, пакеты можно взять с
PyPI. Категорически рекомендую пользоваться pipx, а запускать doc2dash проще всего такой командой:
$ pipx run doc2dash --help
Есть здесь и продвинутый совет #дляпрофи: если вы разбираетесь в PyPy, умеете им пользоваться, а также планируете сконвертировать огромные деревья с документацией. Итак, совет: doc2dash более чем вдвое прибавляет в скорости, если работать с PyPy, а не с CPython.
Если вы ничего из этого раздела не поняли – просто забудьте о нем и возьмите чашечку горячего кофе.
Собираем документацию
Далее переходим к самой серьезной проблеме, из-за которой поступают новые запросы на доработку doc2dash: вся документация нам нужна в полной, собранной форме. Как правило, это означает, что вам нужно скачать репозиторий и самостоятельно разобраться, как скомпоновать документацию – и только затем переходить к установке doc2dash. Дело в том, что на большинстве сайтов с документацией отсутствует возможность скачать всю документацию целиком.
Вот что я придумал: сначала поискать tox.ini
или noxfile.py
и посмотреть, собирает ли он документацию. Если нет – поискать readthedocs.yml
, а если и это не удастся – искать конкретные файлы с названиями вроде docs-requirements.txt
или опциональные цели для установки, например, docs
. Последняя надежда – пройтись по страницам YAML и проверить конфигурации CI.
Как только вы справитесь с установкой всех зависимостей, вам, скорее всего, останется сделать только make html
в каталоге с документацией.
Когда справитесь со всем этим, у вас должен получиться каталог _build/html
для Sphinx или site
для MkDocs.
Обратите внимание: в случае с MkDocs, если в проекте не используется расширение mkdocstrings – увы, сегодня это можно сказать практически про все популярные проекты – у вас не окажется файла objects.inv
и, следовательно, не будет данных API, которые можно было бы потреблять.
Искренне надеюсь, что появится больше проектов на основе MkDocs, в которых добавится поддержка mkdocstrings! Этот инструмент, как Sphinx, также не зависит от языка.
Преобразование
За самым сложным этапом следует самый простой: преобразуем в docset ту документацию, которую только что собрали.
Все, что требуется для этого сделать – указать doc2dash на каталог с HTML-документацией и ждать:
$ doc2dash _build/html
Вот и все!
doc2dash умеет извлекать имя из индекса intersphinx и использует это имя по умолчанию (его можно переопределить при помощи --name
). У вас должно получиться добавить этот docset в обозреватель API на ваше усмотрение – после этого все должно работать.
Если передать --add-to-dash
или -a
, то финальная версия docset автоматически добавится в Dash, когда все будет готово. Если передать --add-to-global
или -A
, то готовый docset будет перенесен в глобальный каталог (~/Library/Application Support/doc2dash/DocSets
) и добавлен оттуда. При создании docset для собственных нужд я редко использую doc2dash без -A
.
Улучшаем набор документации
По документации к Dash есть ряд рекомендаций по улучшению того docset, что был собран на предыдущем этапе. Здесь важно отметить, что следующие несколько шагов строго опциональны, и я часто ими пренебрегаю, так как ленив.
Но в данном случае я хочу отправить docset в предоставленный пользователем реестр Dash, так что давайте пройдем этот путь от начала и до конца!
Готовим главную страницу
В Dash всегда можно поискать все установленные docsets, но иногда поле поиска хочется ограничить. Например, при вводе p3:
(двоеточие здесь значимое), то Dash начинает искать только по docset от Python 3. Еще до того, как вы начнете вводить текст, под поисковым полем откроется меню, первым элементом которого будет «Main Page».
При преобразовании документов structlog эта главная страница содержит индекс, который может быть полезен, но мне он обычно не нужен. Выходя на главную страницу, я обычно собираюсь полистать повествовательную документацию.
В doc2dash опция для установки главной страницы называется --index-page
или -I
, здесь (относительно корня документа) принимает имя того файла, страница которого вас интересует.
Здесь можно запутаться, так как имя файла с индексом — genindex.html
, а имя файла с главной страницей — index.html
, как обычно в HTML. Следовательно, добавляем в командную строку --index-page index.html
.
Добавляем иконку
Наборы с документацией могут сопровождаться иконками, которые расставлены по всему Dash рядом с именами и символами docsets. Это не только красиво, но и помогает быстрее узнавать нужный docset. Если же вы ищете информацию сразу по многим docsets, то понятно, откуда берется символ.
У structlog на логотипе милый бобёр, так что давайте в ImageMagick изменим размер этого логотипа, чтобы он составлял 16x16 пикселов:
$ magick \
docs/_static/structlog_logo_transparent.png \
-resize 16x16 \
docs/_static/docset-icon.png
Теперь его можно добавить в docset, воспользовавшись опцией --icon docset-icon.png
.
Поддержка онлайновой переадресации
Оффлайновые документы великолепны, но иногда бывает полезно перейти к онлайновой версии той страницы с документацией, которую вы сейчас читаете. Как правило, это делается, чтобы свериться с более новой или более старой версией.
В меню Dash для этого есть элемент «Open Online Page ⇧⌘B», но инструменту нужно сообщить базовый URL к документации. Это можно задать при помощи --online-redirect-url
or -u
.
Что касается пакетов Python, лежащих на Read the Docs, там можно выбирать между версиями stable
(отмечена как наиболее актуальная в системе контроля версий) и latest
(актуальная главная ветка).
Думаю, с latest
целесообразнее в случаях, если вы не хотите расставаться с комфортом, присущим оффлайновой документации. Поэтому добавлю:
--online-redirect-url https://www.structlog.org/en/latest/
Всё вместе
Готово! Давайте выполним все, что записано в командной строке и посмотрим, как это выглядит в Dash:
$ doc2dash \
--index-page index.html \
--icon docs/_static/docset-icon.png \
--online-redirect-url https://www.structlog.org/en/latest/ \
docs/_build/html
Converting intersphinx docs from '/Users/hynek/FOSS/structlog/docs/_build/html' to 'structlog.docset'.
Parsing documentation...
Added 238 index entries.
Patching for TOCs... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Чудесно:
![Главная страница structlog Главная страница structlog](https://habrastorage.org/getpro/habr/upload_files/0d1/c09/a86/0d1c09a868db34d414c238972de766a8.png)
Обратите внимание на иконку в поисковой строке. Если я нажму ⇧⌘B на любой странице с якорем, то перескочу к тому же месту в новейшей версии онлайновой документации.
Автоматизация
Поскольку я хочу создавать новую версию docsets для каждого нового релиза, подготовку этих версий нужно автоматизировать. В structlog «Действия» (Actions) GitHub уже используются как средство непрерывной интеграции, поэтому целесообразно воспользоваться тем же механизмом и для сборки docset.
Применительно к локальному тестированию мне очень пригодится, что проект doc2dash написан на Python, и я могу работать в среде tox, повторно использующей все те же зависимости, что были задействованы и при тестировании самой документации.
tox – это комбинация make и менеджера виртуальной среды. tox основан на файловом формате ini
. Исходно он предназначался для тестирования программ на Python сразу для многих версий Python, но в итоге превратился в гораздо более мощный инструмент.
Он сильно выигрывает по сравнению с Makefile
, поскольку отлично портируется, а также в нем встроена функция подготовки пакетов для Python (так или иначе, она необходима для сборки документации).
Среда устанавливает structlog[docs]
– т.e., пакет с опциональными зависимостями docs
, плюс doc2dash. Затем по порядку выполняет следующие команды:
[testenv:docset]
extras = docs
deps = doc2dash
allowlist_externals =
rm
cp
tar
commands =
rm -rf structlog.docset docs/_build
sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs docs/_build/html
doc2dash --index-page index.html --icon docs/_static/docset-icon.png --online-redirect-url https://www.structlog.org/en/latest/ docs/_build/html
cp docs/_static/docset-icon@2x.png structlog.docset/icon@2x.png
tar --exclude='.DS_Store' -cvzf structlog.tgz structlog.docset
Далее я могу собрать docset, просто вызвав tox -e docset
. Пока в doc2dash сохранится поддержка иконок в высоком разрешении, он также копирует крупную версию логотипа, 32x32 пикселя, непосредственно в docset.
Сама эта операция тривиальна, но для нее требуются простыни шаблонного кода, так что я просто оставлю ссылку, иллюстрирующую рабочий поток. Обратите внимание на действие upload-artifact
в конце, позволяющее мне скачать собранные docsets из сводок отдельных прогонов.
На данном этапе у нас уже есть отличный docset, собранный автоматически. Давайте выставим его на всеобщее обозрение!
Выкладка
На заключительном этапе отправим наш docset в репозиторий Dash, который заполняют пользователи, так, чтобы другие специалисты могли с удобством скачать его через графический пользовательский интерфейс Dash. В данном случае удобно, что в Dash используется концепция целого процесса, такого, с которым знакомы, пожалуй, все фанаты опенсорса: речь идет о таких пул-реквестах, как в GitHub.
Первым делом сверяемся со списком Docset Contribution Checklist. К счастью, мы – или, в некоторых случаях, doc2dash – уже обо всем позаботились!
Итак, идем дальше, делаем форк репозитория https://github.com/Kapeli/Dash-User-Contributions и клонируем его на наш компьютер.
Сначала копируем директорию Sample_Docset
в docsets
, переименовывая ее при этом. У меня командная строка принимает следующий вид:
$ cp -a Sample_Docset docsets/structlog
Давайте зайдем в каталог через cd docsets/structlog
и отсюда двинемся далее.
Самое главное в данном случае – добавить сам docset, но в виде tar-файла, упакованного в архиве gzip. В руководстве для контрибьюторов даже предоставляется шаблон для этой цели. В моем случае командная строка примет вид:
$ tar --exclude='.DS_Store' -cvzf structlog.tgz structlog.docset
Возможно, вы успели заметить, что я уже упаковал в архив tar мой файл tox, поэтому мне остается просто его скопировать:
$ cp ~/FOSS/structlog/structlog.tgz .
Кроме того, он хочет иконок сверх тех, что лежат в docset, поэтому я копирую их из docset:
$ cp ~/FOSS/structlog/structlog.docset/icon* .
Далее нам следовало бы заполнить метаданные в файле docset.html
, и в моем случае это делается очень просто:
{
"name": "structlog",
"version": "22.1.0",
"archive": "structlog.tgz",
"author": {
"name": "Hynek Schlawack",
"link": "https://github.com/hynek"
},
"aliases": []
}
Наконец, от нас требуется коротко написать, кто мы такие, и как собирать docset. Ознакомившись с другими примерами, я остановился на следующем варианте:
# structlog
<https://www.structlog.org/>
Maintained by [Hynek Schlawack](https://github.com/hynek/).
## Сборка Docset
### Требования
- Python 3.10
- [*tox*](https://tox.wiki/)
### Сборка
1. Clone the [*structlog* repository](https://github.com/hynek/structlog).
2. Check out the tag you want to build.
3. `tox -e docset` will build the documentation and convert it into `structlog.docset` in one step.
Фокус с tox оправдался - теперь мне никому не придется объяснять, как упаковываются пакеты в Python!
Не забудьте удалить остатки «рыбы» об образце docset, эта информация нам не нужна:
$ rm -r versions Sample_Docset.tgz
Готово! Давайте проверим, что у нас с изменениями:
$ git checkout -b structlog
$ git add docsets/structlog
$ git commit -m "Add structlog docset"
[structlog 33478f9] Add structlog docset
5 files changed, 30 insertions(+)
create mode 100644 docsets/structlog/README.md
create mode 100644 docsets/structlog/docset.json
create mode 100644 docsets/structlog/icon.png
create mode 100644 docsets/structlog/icon@2x.png
create mode 100644 docsets/structlog/structlog.tgz
$ git push -u
Выглядит хорошо – время делать пул-реквест!
Через несколько часов:
![Предложенный нами structlog docset лежит в Dash! Предложенный нами structlog docset лежит в Dash!](https://habrastorage.org/getpro/habr/upload_files/bfa/079/593/bfa0795935470b3205d65e94f02549d2.png)
Определённо, это успех: теперь любой может скачать structlog Documentation Set, и на этом наше краткое руководство завершается!
Заключение
Надеюсь, мне удалось и немного подогреть ваш интерес к документации API, и разоблачить некоторые заблуждения, касающиеся создания собственных наборов документации. Я ставил перед собой цель прокачать навыки тем программистам, кто – как и я – закапываются в бесчисленных пакетах, которые необходимо держать в уме, чтобы справиться с задачей.
Но превыше всего я надеюсь, что моя статья вдохновит кого-нибудь помочь мне с добавлением новых форматов в doc2dash, чтобы еще больше стало таких программистов, которые могут позволить себе роскошь иметь всю документацию по API прямо на кончиках пальцев.
Кроме того, закончив эту статью, я стал надеяться, что Zeal удастся оживить. Говорят, он давно застопорился, и последнему релизу уже четыре года. Поскольку это опенсорсный проект, было бы круто, если бы к нему подключились новые руки, и мы располагали бы хорошими обозревателями API на всех платформах.
Комментарии (34)
DreamShaded
07.10.2022 00:24Кроме того, закончив эту статью, я стал надеяться, что Zeal удастся оживить. Говорят, он давно застопорился, и последнему релизу уже четыре года
ну, он неплох по дизайну, работает, документация обновляется, да и всё-таки коммиты есть свежие. Полагаю, что он будет жить ещё долго и счастливо)
beeptec
07.10.2022 11:19+1Каждый раз на профессиональных собесах после каверзных хрестоматийных вопросов со стороны интервьюера, перед тем как принять решение, буду я в этой фирме продолжать свою карьеру или нет, я отвечаю приблизительно так - "по возможности стараюсь не захламлять свои мозги справочной информацией, при этом я владею опытом быстрого ее поиска
datasheet или дисклеймер правильных источников и могу продемонстрировать, как я это делаю.Все это происходит молниеносно – я хочу, чтобы на путь в оба конца уходило менее 2 секунд. Такая скорость и нужна, чтобы не терять концентрацию и не забывать, чем занимаешься. Я уже научился делать все это на автомате.
Для этого, в своей сфере, применяю собственные FSM билдеры и фреймворк, когда нужно просто кликнуть на некий элемент - артефакт.
DenisPantushev
07.10.2022 14:15+7Прикольно, но к концу чтения я уже все позабыл, наверное у меня память как у этой... не помню. Можно эту статью оформить в виде подробной документации?
nektopme
08.10.2022 13:22НЕ туда копаем, коллеги - компьютерные хитрости не превзойдут возможностей заложенных в нас.
В основном, мы визуальные мыслители образами - мы хорошо запоминаем интересные фильмы.
Информацию в виде слов, символов, чтобы запомнить, придётся преобразовывать в интересные запоминающие фильмы, не всех не обучили этому.
Некоторые помнят, раньше было - прочитал главу учебника и понял и запомнил.
А теперь не так.
Обилие БЕЗобразной, полезной, но в виде НЕ удобном для запоминая, без Образа, вынудила организмы не создавать живые картинки, экономить силы и запоминать "фотографически", но этот способ не для нас.
Меньшая часть из нас умеет выполнять преобразования в фоне - на вход много слов и символов, а внутри интересные кины.
Они хорошо вспоминают и доминируют над нами (не преобразовывающими информацию в удобрение для "памяти").
И учебники такие же пишут: хорошие, но бесполезные для большинства.
После изучения книг, типа "Эйнштейн гуляет по Луне", про визуальное мышление, мнемотехники, успокоился и иду по пути - полезнее заново восстанавливать фоновые способности запоминать ярко, интересно, легко, творчески - если не запомнил, значил запоминал не творчески.lair
08.10.2022 18:22Мне вот интересно, если я плохо запоминаю даже интересные фильмы, то что мне делать?
nektopme
08.10.2022 18:34Если есть интерес, то шансы восстановить природные способности высоки.
У Вас есть навыки интеграции библиотек в свои проекты?
Есть "библиотеки", восстанавливающие способности памяти, осталось узнать Ваш интерфейс.lair
08.10.2022 18:45"Восстановить" можно что-то, что было раньше. Но в моей жизни не было периода (ну или я его не помню, вот ирония), когда я легко что-то запоминал.
nektopme
08.10.2022 19:14Опишите как у Вас происходит "плохо запоминаю" и "легко что-то запоминал", а то может Ваше "плохо" для меня "хорошо".
lair
08.10.2022 19:30-1Опишите как у Вас происходит "плохо запоминаю"
Ну вот вы говорите: "мы хорошо запоминаем интересные фильмы". Я не знаю, я из интересного фильма помню в лучшем случае общий замысел и какие-то повороты сюжета. Пару реплик, может быть. Один-два кадра иногда. Через год — и того меньше. Через пять — ничего, кроме названия. Имена актеров? Исключительно редко. Имена режиссеров? Почти никогда. Год выпуска — никогда.
"легко что-то запоминал"
Ну вот пароли я нормально запоминаю: удачный пароль (восемь алфавитно-цифровых символов) я обычно могу ввести без подсказки со второго дня рутинного использования. Это, возможно, единственное, что я запоминаю без усилий.
nektopme
08.10.2022 20:32-1Давайте улучшим "плохо запоминаю даже интересные фильмы":
В подходящем ли состоянии Вы приступаете к просмотру?
Может вы отвлекаетесь во время просмотра?
Попробуйте запоминать не весь фильм целиком, а меньшими частями.
Какой фильм Вам будет интересно и полезно запомнить?
Теперь Ваша жизнь не будет прежней :-)lair
09.10.2022 01:02В подходящем ли состоянии Вы приступаете к просмотру?
Когда как, но чаще — да.
Может вы отвлекаетесь во время просмотра?
Да, отвлекаюсь.
Попробуйте запоминать не весь фильм целиком, а меньшими частями.
Для этого придется его пересматривать, причем пересматривать частями. Мне кажется, даже если бы у меня было время на пересматривание, пересматривание частями противоречит авторскому замыслу.
Какой фильм Вам будет интересно и полезно запомнить?
Интересно — где-то половину просмотренных. Полезно — все просмотренные.
Теперь Ваша жизнь не будет прежней
Неа. Ничего не изменилось.
nektopme
09.10.2022 08:38Может быть Вы делаете, что-то лишнее, что мешает запуску встроенного механизма создания образов?
Проверьте статью.
Там утверждается:
"Язык мозга – это зрительные образы.
Ваш мозг не сможет запоминать знаковую информацию, пока вы не научитесь преобразовывать их в понятные мозгу зрительные образы. "
Вы же программист?
Хоть немного можете запоминать знаковую информацию?
Значит есть что улучшать.
Рефлексируйте себя, покройте себя юнит-тестами.
Изменяйте методы просмотров фильма: скорость, позу и т.д.
Вы пишите:
"Для этого придется его пересматривать, причем пересматривать частями."
Ну да - не можете поднять 50 кг за раз, начинаете работать с меньшими весами - разделяй и властвуй. Несколько раз.
"противоречит авторскому замыслу."
Что там мыслил автор, сейчас не учитываем.
Он может и не знал, что его фильм будет лишь гантелей.
Отнеситесь к себе как к сервису, который Вы учите воспроизводить просмотренное.lair
09.10.2022 14:28Может быть Вы делаете, что-то лишнее, что мешает запуску встроенного механизма создания образов?
Может быть. А может быть, я ничего лишнего не делаю, и "встроенный механизм" — работает.
Проверьте статью.
Там утверждается:
"Язык мозга – это зрительные образы.
Ваш мозг не сможет запоминать знаковую информацию, пока вы не научитесь преобразовывать их в понятные мозгу зрительные образы. "Я не могу проверить эту статью. Для этого нужен эксперимент, для которого у меня нет ни ресурсов ни навыков.
Но, что важнее, я не могу поверить этой статье. В ней нет ни одной ссылки на другую литературу или исследования, кто ее автор — тоже неизвестно. Так почему я должен ей доверять?
(При этом написана она в том стиле, который у меня ассоциируется с лженаукой, и поэтому доверия не вызывает. Но это так, предрассудки.)
Вы же программист?
Хоть немного можете запоминать знаковую информацию?В этом-то и дело. Статья, на которую вы ссылаетесь, утверждает, что я не мог бы этого делать, не преобразовывая эту информацию в зрительные образы — но это не так. Та информация о программировании, которую я помню, содержится в моей голове в виде смысла. "Свойство от поля отличается вот тем-то". Никаких зрительных образов, только понимание (даже не определение, определение я как раз не помню, и вывожу из понимания).
Или, пример из другой моей области знаний: "сонатная форма (точнее, форма сонатного аллегро) — это форма, характеризующаяся следующим устройством ...". Аналогично, у меня нет в голове зрительных образов, соответствующих главной или побочной партии, их тональным соотношениям и так далее. Это все абстрактные понятия, и их сила именно в том, что они абстрактны.
Или вот я помню, как звучит валторна, а как — кларнет, а как — гобой. Я узнаю эти звуки на слух, но визуальные образы с этим связаны только потому, что я знаю, как выглядит валторна, кларнет или гобой. "Что это звучит? Явно не медь, но яркое и округлое — кларнет" — и только потом, как ответ на слово кларнет, будет картинка инструмента. А вот как выглядит челеста, я не знаю вовсе, но звук узнаю.
Так что статья, на которую вы ссылаетесь, еще и противоречит моему жизненному опыту. Так почему я должен ей доверять?
Значит есть что улучшать.
Да, но что? Я запоминаю, как вы выражаетесь, "знаковую информацию" лучше, чем визуальную. Так почему я должен привязываться к неэффектикному для меня способу запоминания?
Рефлексируйте себя, покройте себя юнит-тестами.
Вы знаете, да, какая самая важная характеристика юнит-теста? Воспроизводимость. А то, что вы мне предлагаете, не является воспроизводимым объективным экспериментом.
Он может и не знал, что его фильм будет лишь гантелей.
Ваша метафора предполагает, что если один (или несколько) фильмов запомнить по частям, то дальше фильмы будут запоминаться целиком. Но совершенно не понятно, из чего делается такой вывод.
Отнеситесь к себе как к сервису, который Вы учите воспроизводить просмотренное.
Вам, возможно, это покажется странным, но я не хочу и не планирую относиться к себе, как к сервису, единственная задача которого — воспроизводить просмотренное. Фильмы для меня — развлечение, а не профессия.
nektopme
09.10.2022 14:46-1Да я понял, что Вы развлекаетесь, но следующий фильм Вы уже попробуете запомнить получше.
И получится.
Плацебо.
nektopme
09.10.2022 14:53-1Вы употребили "выглядит", "основа".
Расцениваю как подтверждение утверждения:
"в основном, мы визуальные мыслители".
lair
09.10.2022 14:56Расценивать-то вы можете что угодно любым удобным вам образом. Вот только более достоверным ваше утверждение от этого не станет.
AAngstrom
09.10.2022 12:26+3В основном, мы визуальные мыслители образами - мы хорошо запоминаем интересные фильмы.
Это опасный стереотип. Во-первых, у любого человека, не обладающего нарушениями умственного развития, функционируют все типы мышления, но да -- развиты они в разной степени у разных людей. Во-вторых, даже если полагать, что визуальное мышление доминирует в среднем по больнице, то в среде учёных/инженеров есть сильный перекос в сторону людей с аналитическим мышлением, оперирующим абстрактными образами в виде правил, слов и других лексических единиц (например, математических символов). И таким людям запомнить суть хорошо структурированного текста гораздо проще, чем набор картинок или информацию, поданную в виде, прости-господи, видео-клипа. В третьих, художественные фильмы несут совершенно другой тип информации, нежели тот, который обычно представлен в документации или учебнике. Фильмы, они про эмоции, и интересный фильм должен, в первую очередь, "цеплять". Этим он, собственно, и может запомниться. А какие там были кадры, сцены и т.п., у меня, например, выпадает из головы в течение пары дней после просмотра (сюжет и, иногда даже, имена главных актёров, могут продержаться намного дольше).
А опасен этот стереотип как раз тем, что люди с реально хорошо развитым визуальным мышлением, считают, что такие вокруг все, и вместо понятных чётких объяснений в текстовой форме (максимум с диаграммами и графиками) пропихивают везде дурацкие видео-туториалы, видео-описания и прочий информационный мусор, среди которого трудно найти то, что нужно.
nektopme
09.10.2022 14:38Статья не для тех, кто хорошо запоминает символы - они хорошо, сами себе, в фоне создают образы, поэтому им явные образы не нужны.
А для тех кто, заметил, что символьная информация стала хуже запоминаться.
Им поможет обращение внимания на создание образов - фоновый процесс создания образов у них ухудшился.
Astroscope
09.10.2022 13:09Информацию в виде слов, символов, чтобы запомнить, придётся преобразовывать в интересные запоминающие фильмы, не всех не обучили этому.
О, нет! Не нужно то, что понятно объяснимо несколькими абзацами текста - текста, читаемого с удобной для читателя скоростью, иногда со схематическими иллюстрациями, превращать в получасовый треп в ютубе, который идет с удобной для диктора, а не слушателя скоростью, где практически невозможно притормозить на непонятном или требующем обдумывания месте, равно как и практически невозможно ускорить понятные или уже известные фрагменты, на которые не нужно тратить время слушателя. Техническая возможность перемотать, поставить на паузу или изменить скорость воспроизведения практически почти бесполезна против возможности читать текст с субъективно удобной скоростью. А иллюстрации - отдельный ад, когда вместо разглядывания иллюстрации и сверки с описанием в тексте так долго, как требуется конкретному читателю, приходится судорожно жать на паузу, чтобы разглядеть хоть что-то.
Нет, спасибо, не надо. Видео бесспорно хорошо для иллюстрации некоторых процессов, но таких - абсолютное меньшинство. Глобально видео "рулит" в таких областях, как киноискусство, тогда как в околотехнических вопросах видео чаще зло, бессмысленное и беспощадное.
vap1977
08.10.2022 22:10Прямо ностальгией накрыло :)
Вспомнился Norton Guide из начала-середины девяностых. Он сидел в памяти под DOS как резидентная программа, всплывал и убирался по горячим клавишам, и показывал документацию в своем простом формате. Я тогда всю имеющуюся доку в его формат перевел.
Потом, уже году в 98-м, когда на линукс пересел, настроил в fvwm2 горячие клавиши и управление окнами и рабочими столами, чтобы от окна с кодом мгновенно переключаться на окна с разной документацией и обратно. Тот конфиг fvwm2 до сих пор со мной, под ним и живу.
saipr
Всё здорово, спасибо, но что делать-то тем, у кого память как у дрозофилы?
Areso
у меня Obsidian. Для каких-то частых кейсов.
Оффлайн документация в одном месте - реально круто, потому что я часто летаю, мне пригодится :)
capjdcoder
Obsidian это интересно, но как туда подтянуть документацию автоматически? Я тоже использую его, поделитесь?
QuAzI
Obsidian крут, но для записок сумасшедшего, которые ты сам ведёшь, например какие-то логи по отдельным задачам. Но что делать-то тем, у кого память как у дрозофилы? И проблемы с концентрацией... особенно последние 2.5 года... даже при том, что большинство отвлекающих ресурсов в /etc/hosts уже прописаны как 127.0.0.1. И нужно постоянно учить что-то новое или оставлять заметки на полях, желательно так, чтобы не продолбать их в файлопомойке которой десятки лет.
К тому же нужно мордовать настройки по умолчанию, иначе сторонний софт немножечко обломается об ссылки и картинки. Я, например, конфигурил
Default location for new files: Same folder as current file
New link format: Relative path to file
Use [[Wikilinks]]: off - ввод [[ всё равно работает, он сам заменяет их на MD и сам дописывает relative path если он включен
Default location for new attachments: In subfolder under current folder
Subfolder name: плагин Custom Attachment Location переписывает на
./${filename}.files
чтобы ресурсы можно было с MD переносить куда угодно из FMТеперь можно вести какие-то записи в приемлемом формате просто через Ctrl+O project/date_issue
Можно завести template для выставления таймстампа и в daily notes трекать, над чем ты начал работу, чтобы в конце месяца не взрывать себе мозг вопросом "как затрекать то, что прошло мимо git".
Отчёт по
git
прописать в.gitconfig
можно, например, такостальное брать из obsidian, номер таски оформлять как ссылку, ссылку [[issue_num]] обсидиан заменяет на полный путь (включая поддиректории)
В поддиректории я в таску накидываю: заголовок таски, номер в трекере (оформлен как ссылка на трекер), основной мессадж и, если нужно, картинки. Затем по ходу работы дописываю всё что пришлось ковырять (куски логов, SQL-запросы, бекап записей БД перед их изменением, скрины и даже REST-запросы ...). Получается по каждой задаче директория в которой есть основной файл с контекстом и его ресурсы.
Так же по мере работы я могу этот Markdown открыть в DataGrip/Rider/VSCode и он заиграет вообще новыми красками, потому что DataGrip умеет выполнять запросы прямо из вставок в MD-файл, получается своеобразный аналог Jupyter Book, когда у тебя есть история, примеры кода и сразу же можно его выполнить. Цветастые логи подсвечивающие ошибки и ворнинги (ideolog), HTTP Client (для VSCode лучше httpyac) для REST/GraphQL. Вообще у VSCode вроде есть Foam как "аналог" Obsidian, но я не добрался посмотреть.
С учётом того, что у инструментов JetBrains тоже прослеживается стиль "Нажмите хоткей и получите быстрый поиск по всему", выглядит сильно похоже. Нужно посмотреть, какие там у JB есть интеграции с Dash, Velocity or Zeal. Но это про внешние какие-то хорошо задокументированные штуки, а не про внутренние проекты, к которым документации почти нет, либо она размазана по всяким упоротым конфлюенсам, либо протухла. И всё ещё непонятно как тут прикрутить всякий swagger.
Ну и хочется, конечно, чтобы у JB был более фичастый Markdown и пока не все плагины поддерживают раскрашивание синтаксиса в превью, но, думаю, с ростом сложности всего этого айтизоопарка это будут вынуждены пофиксить.
General_Manjago
Спасибо за советы! Использую обсидиан, казалось бы, простые советы по настройкам, но очень помогли!
QuAzI
Всегда пожалуйста. Обсидианом я пользуюсь сравнительно недавно, ещё пробую покрутить и плагины. Интеграция с Jira, например, пока глючновата, но фиксят очень быстро. Вообще с плагинами там всё сильно лучше, чем с самим обсидианом, у которого ответят может и быстро, но менять "дефолты" на чуть более человеческие и менее деструктивные (с точки зрения классического Markdown, чтобы файлы мог процессить любой софт и не спотыкался об wikilinks, ссылки без путей...) как-то не спешат. Опять же, в отличие от Foam разработка у обсидиана закрыта.
По сабжу, я попробовал потыкать интеграцию в JB, разумеется сразу пролетел мимо Dash (т.к. у меня никсы и Windows), поставил Zeal и Velocity. Выяснилось что плагин нифига не интегрирует, а просто по хоткею запускает одну из программ. Так себе интеграция. Наборы документации примерно одинаковы. Но локально Zeal документацию как-то распаковывает, в итоге у него файлов в хранилище больше и весит всё примерно вдвое больше. Но зато шевелится чуть получше, открытый и не падал при скачивании документации. Кажется из Docsets всё-таки Zeal (для себя) и DevDocs (который можно поднять как локально, так и как сайт) всё-таки лучший выбор. ЕСЛИ Docsets всё-таки вам понравится и вы вообще будете этим пользоваться. Потому что сейчас это выглядит как просто локальная помойка веб-фарша. У каждого автора свой стиль ведения документации, а поиск довольно топорный из-за чего некоторые темы всё же проще проще нагуглить, особенно если темы чуть сложнее вызова одной функции из API, нет единого стиля оформления, нельзя найденную функцию as is воткнуть обратно в IDE, нужно прям мышковозить... сам софт настраивается так себе и пока не очень понятно, как нормально с этим жить с клавиатуры
Примеры документации открытой в Zeal
Да и в общем совершенно непонятно, как автору не хватило родной документации к тем же модулям на python, которую подтягивает любая приличная IDE и отобразит НОРМАЛЬНО, без цирка с понями. И уж тем более непонятно, зачем натягивать сову на глобус и конвертить всякий нормальный Markdown по которому в рамках проекта IDE может делать текстовый поиск в веб-портянку требующую прям отдельного браузера. Тогда уж уместнее был бы параметр меню FM "открыть директорию в Obsidian" и не теребить людям мозг. А ещё лучше было бы затянуть аналогичный обсидиану функционал в JB и VSCode и забыть про эти костыли как страшный сон
Alexeydax
Теперь все здорово. Спасибо огромное Вам!
psydvl
А сниппеты тоже там или где-то ещё?
Areso
сниппеты в gist.github.com
tba
Хотел написать, но уже забыл