Использование узловых модулей для предоставления офлайн-документации
Представляем Module Docs, пакет Node, который обслуживает файлы README из каталога node_modules ваших приложений.
Вы молодой, модный и активный разработчик? Я тоже, но я, как правило, занимаюсь разработкой приложений в ситуациях, когда у меня нет доступа к Интернету. К тому же я не модный. А молодость мимолетна.
Так или иначе.
Есть очень хорошие решения для получения offline-документации. На ум приходит DevDocs, потому что он предлагает отличное автономное хранилище документации для большого количества широко используемого программного обеспечения и имеет массу функций. Фактически, вам, вероятно, следует просто использовать это. Однако вы не можете просто добавить офлайн-документацию к любому пакету, который вам нужен. Происходит некоторая задержка.
Если существующее решение, такое как DevDocs, не соответствует вашим потребностям, вы можете использовать документацию, поставляемую с пакетами, которые вы установили в своем приложении. Верно, я говорю о README.md файлах.
На выходных ™ ️ у меня возникла идея создать небольшой инструмент CLI, который мог бы создать экспресс-сервер, который будет искать каталог node_modules и обслуживать содержимое README.md файла каждого пакета. Инструмент также предоставит вам веб-интерфейс для поиска node_modules пакетов. Он также может использовать IndexedDB для хранения избранного в автономном режиме.
Так я и сделал. Результатом является Документация модуля, и вы можете установить его как пакет Node.
Вы можете установить его глобально или для каждого проекта. После установки запустите cli, запустив:
$ module-docs start
Вы можете создать сценарий npm, который будет автоматически запускаться module-docs как часть процесса разработки. Вот как я его использую:
{
...
"scripts:" {
"start": "npm run start:docs && webpack-dev-server",
"start:docs": "module-docs start"
}
...
}
Вы можете настроить module-docs для каждого проекта, в котором хотите его использовать, создав module-docs.config.js файл в корне каталога этих проектов. В настоящее время вы можете предоставить массив имен пакетов для включения в избранное, например:
// module-docs.config.js
module.exports = {
favorites: ["react", "react-apollo", "react-apollo-hooks"]
}
Если вы просто хотите использовать его, вы можете перестать читать здесь и жить своей лучшей жизнью. Если вы хотите прочитать о том, как он был построен, благословите и продолжайте читать.
Создание CLI
Чтобы создать cli, я буду использовать commander.js, очень популярный инструмент для создания интерфейса командной строки.
Это отправная точка для всего пакета module_docs. Это то, что позволяет вам запустить module-docs start для запуска экспресс-сервера. Посмотрим на сервер.
Сборка сервера
Сервер представляет собой довольно простую сборку сервера Node с использованием Express. Он использует webpack-dev-middleware для создания сервера разработки, который будет обслуживать приложение React для веб-интерфейса.
Как видите, есть две конечные точки API. Первая конечная точка обрабатывает получение имен каталогов из node_modules. Вторая конечная точка получает README содержимое и анализирует package.json информацию о пакете. В настоящее время пользовательский интерфейс просто отображает версию пакета и ссылку на домашнюю страницу пакета, если таковая имеется.
Для обработки запроса POST я создал FileController. Вот где вся тяжелая работа.
FileController
Этот файл определенно можно было бы подвергнуть некоторому рефакторингу. При этом я разобью этот файл на части. Во-первых, служебные функции и импорт:
Важно отметить, что я создал черный список файлов, которые нужно исключить из поиска, поскольку они находятся в node_moudles, но бесполезны для наших целей. Я уверен, что этот список не исчерпывающий.
Кроме того, мы должны предоставить список подкаталогов (дочерних), которые содержат файлы README и package.json, на случай, если рассматриваемый пакет является монорепозиторием или пакетом с ограниченной областью видимости, например babel. Это то, что делает getPackagesFromChildren.
Вышеупомянутые служебные функции будут использоваться в FileController обработчиках. Давайте посмотрим на них.
Это почти все, что касается серверной части.
Что касается внешнего интерфейса, он построен с использованием React (на момент написания 16.8-alpha, поэтому я могу использовать эти сладкие сладкие крючки). Лучше всего открыть CodeSandbox ниже и поэкспериментировать с кодом интерфейса в каталоге client.
Заворачивать
Неплохо для выходных. Я собираюсь продолжить работу над некоторыми другими функциями, которые я лично хотел бы использовать, например, возможность добавлять собственные примечания к каждому пакету, а также иметь возможность связывать и получать документацию, а также сохранять ее в автономном режиме. Дайте мне знать, что вы думаете!
Рамзи - разработчик полного цикла JavaScript в компании по анализу данных в Спрингфилде, штат Вирджиния. Вы можете подписаться на него в твиттере или гитхабе. Ему нравится, когда ты это делаешь.
