Last week I Learned

У нас на работе используется Sphinx как часть процесса сборки и публикации документации для наших продуктов. Sphinx это популярный, среди python-разработчиков, генератор документации. Исходный формат который он использует - reStructuredText. Вообще формат изобрели в питоновских docutils https://docutils.sourceforge.io/rst.html. Спецификация формата https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html. Сам пакет docutils содержит несколько утилит для генерации документов в разных форматов из rst-файлов https://docutils.sourceforge.io/docs/user/tools.html.

Мне хотелось оптимизировать процесс сборки документации и для этого я хотел бы использовать JavaScript. Но оказалось, что формат reStructuredText не очень популярен в js-экосистеме. Нашлось с десяток пакетов разной степени убогости, но ни одного удовлетворительного качества https://www.npmjs.com/search?q=keywords:reStructuredText.

https://pypi.org/project/sphinx-autobuild/ - фактически dev-сервер для удобной разработки sphinx-проекта. Не получилось быстро прикрутить, так как у нас разделены исходники документации и сам проект с настройками и плагинами для sphinx. И настраивается всё вместе не очень просто.

Так как у нас то, что собрал sphinx потом кастомными скриптами снаружи подготавливается для сборки конечного сайта с jekyll, то могут пригодится такие пара плагинов для sphinx: https://pypi.org/project/sphinx-markdown-builder/ и https://pypi.org/project/sphinx-jekyll-builder/. Последний делает примерно то, что нам нужно. Даже если они не подойдут в таком виде, то можно на их основе сделать то, что нужно, так как кода там довольно мало.

11ty - популярный генератор сайтов написанный на JavaScript. Быстро работает и очень гибко настраивается. Поддерживает с десяток шаблонизаторов. Но вот добавить свой шаблонизатор оказалось непросто. Есть закрытый тикет на поддержку кастомных экстеншенов. Он закрыт, но при этом совершенно непонятно сделан он или нет, так как в проекте используется очень странная политика по ведению задач. Даже есть объяснение: "This repository is using lodash style issue management for enhancements (see https://twitter.com/samselikoff/status/991395669016436736) This means enhancement issues will now be closed instead of leaving them open.". В итоге заглянув в этот проект в первый раз совершенно невозможно понять, что там сделано, а что нет. Привязывать коммиты к закрытым тикетам совершенно нормально. В итоге покопавшись в исходниках можно найти, что есть функция addExtension, но работает она только если включен флаг ELEVENTY_EXPERIMENTAL. При этом она никак не задокументирована и что же она ожидает на вход непонятно. Из работоспособных решений нашёл статью https://www.raymondcamden.com/2020/02/19/adding-another-template-language-to-eleventy, но там по факту обходные решения.

Попробовал Nix для python проекта. Не всё прошло гладко. Сам питон установить не проблема, проблемы начинаются с установкой пакетов. Нужно отдельно поставить pip. При этом у меня на MacOS уже какие-то (старые) python и pip стояли и это меня немного сбило. Питон версии 3.10 у меня почему-то не поставился, поэтому я поставил версию 3.9. Найти как поставить pip оказалось совсем не очевидно. Нужно выполнить команду nix-env -qaP '.*pip.*'. И в её выводе найти пакет подходящий под установленную версию python. В моём случае это python3.9-pip-21.0.1. При этом устанавливать пакеты можно только в какой-то virtual env, так как файлы в том месту куда установился python запрещает менять NixOS. Вообще тема с воспроизводимым окружением для Python проекта на NixOS на этом не заканчивается и может напишу отдельный пост про это.

Poetry - относительно новый менеджер для управления пакетами в Python. Умеет делать lock-файлы, т.е. запоминает конкретные версии пакетов вплоть до хеш сумм архивов. Автоматически создает virtual env для проекта. И вообще автоматизирует работу с virtual env. По интерфейсу похож на npm/yarn в nodejs или composer в php.

How to egghead - сайт на котором есть полезные статьи для людей которые хотят стать инструктором на egghead или просто записывать обучающие видео.

QA Wolf - это такая онлайн IDE для написания UI тестов для веб-приложений. Демка на главной странице выглядит круче чем у Cypress. При этом все исходники полностью открыты (у них такая же модель лицензирования как у Sentry https://www.qawolf.com/blog/why-we-open-sourced-everything). Работает на основе Playwright, а значит лишён и некоторых недостатков Cypress, который работает через браузерные api. Кстати, веб-приложение у них написано на Next.js https://github.com/qawolf/qawolf/tree/develop/app, а это редкая возможность покопаться в исходниках реального и относительно большого приложения на Next.js.

https://systemsmanagementschool.medium.com/ - блог ШСМ на английском языке.

https://www.clerk.dev/ - аналог Auth0, только ребята пошли дальше и предоставляют api и готовые react-компоненты не только для входа/регистрации, но и для отображения и редактирования профиля пользователя прямо в приложении.

В V8 добавили ещё один компилятор https://v8.dev/blog/sparkplug. В блоге хромиума уже появилась статья как они благодаря этому начали экономить 17 лет работы CPU каждый день https://blog.chromium.org/2021/05/chrome-is-faster-in-m91.html.

https://www.trailofbits.com/post/discovering-goroutine-leaks-with-semgrep - чуваки научились детектить утечки в горутинах с помощью статического анализа на semgrep.

https://reactjs.org/blog/2021/06/08/the-plan-for-react-18.html - команда React начала работу над новой мажорной версией.