Создавайте компоненты, которые пишут свою собственную документацию
Последние две недели я сосредоточился на том, как быстро создать документацию для моих компонентов Svelte. Я не хочу повторять свою классическую ошибку: создавать какие-то интересные мелочи, но потом не иметь возможности обновлять документацию. Мне нужен способ написать и синхронизировать документацию с кодом. Я пытался понять, как заставить Свелте позаботиться об этом самому. Мне не удалось полностью, но я думаю, что установил общую процедуру.
Шаги
Я исследовал несколько улиц, и в основном они оказались тупиковыми. Первой попыткой было использовать svelte.parse — мне это не подходит. Вторая попытка состояла в том, чтобы попробовать некоторые парсеры JavaScript, начиная с желудя. Еще одна дыра в воде: эти инструменты слишком велики для моей цели. Поэтому мне пришлось сосредоточиться на том, чтобы начать с более низкого уровня. Чтобы иметь самодокумент Svelte, я должен:
Прочтите еще не скомпилированные компоненты Svelte, то есть необработанные .svelte файлы, и извлеките нужную мне информацию:
propsс их именем, типом и значением по умолчаниюactionsкоторые можно выполнить; в этом случае имени достаточно, если оно говорит само за себя- названия слотов, которые можно использовать
- и, хотя я не совсем уверен, переменные CSS, используемые компонентом
- сохранить эту информацию в файле JSON
- делать это автоматически, поэтому вам не нужно помнить об этом
- импортировать эту информацию в Svelte
- использовать определенный компонент для чтения информации и ее автоматического отображения
Поскольку информация о компоненте меняется только во время разработки, то не проблема, если настройка займет пару шагов. Если все автоматизировано, я могу сосредоточиться на самой разработке, не беспокоясь о деталях.
Общая структура
Я решил разделить проект на два разных репозитория:
управлять частью, связанной с извлечением данных
для упрощения отображения различных свойств
Два репозитория еще не завершены. Мне интересно отслеживать шаги, которые я предпринял, и те, которые еще предстоит предпринять. Как только проект станет достаточно зрелым, я интегрирую его в свой шаблон svelte-component-package-starter.
Как получить список реквизитов компонента Svelte
Проблема получения списка свойств компонента Svelte примерно аналогична проблеме поиска слова в текстовом файле. Он включает в себя чтение файла, извлечение его содержимого, а затем его прокрутку, извлекая нужные мне фрагменты.
Итак, я начинаю с создания функции для чтения файла и возврата его содержимого в виде текстовой строки:
Я использую API NodeJS readFileSync. Получив содержимое файла, я начинаю искать то, что меня интересует. Чтобы извлечь свойства компонента, я могу ограничить поиск блоком скрипта:
Я использую регулярное выражение /<script[\s\S]*?>[\s\S]*?<\/script>/gi с string.match(regex), чтобы получить строку. Я использую этот результат для поиска всех let переменных, экспортируемых компонентом, и сохраняю их в массиве. Я использую регулярное выражение /export let [\s\S]*?;/gi:
Получить свойства реквизита
Теперь я могу начать поиск имен реквизита, снова используя регулярное выражение (/(?<=let )(.*?)(?=\s|;|=|:)/):
Следующим шагом является извлечение типов переменных. В этом случае я использую регулярное выражение /(?<=let [:]|[:])(.*?)(?=;|=)/:
Получение значения переменных по умолчанию является более сложным. Я не могу использовать регулярное выражение, слишком много возможных неоднозначных случаев. Я могу использовать хитрость благодаря выбору, который я сделал в начале, когда сохранял каждую переменную let как элемент массива.
Таким образом, я могу считать значением по умолчанию все, что появляется между символом равенства (=) и последним символом строки (который должен быть точкой с запятой ;).
Когда значение по умолчанию является строкой, кавычки должны быть удалены. Для этого я использовал функции isStringType и getStringWithoutQuote:
Создайте объект с информацией
Теперь, когда у меня есть все части, я могу начать собирать их воедино. Я пишу функцию, которая получает name, type и defaultValue:
Затем я создаю функцию, которая читает файл, извлекает значения и возвращает их как объект:
Компонент Svelte
После извлечения всех значений мне нужно выяснить, как их отобразить. Чтобы упростить задачу, я создаю компонент Svelte (el3um4s/svelte-component-info). Я хочу что-то вроде этого:
Первым делом создайте компонент SvelteInfo.svelte и решите, какие реквизиты мне нужны:
Мне нужно имя компонента, имя пакета (для автоматической вставки кода для его загрузки из npm) и, конечно же, вся информация, которую я могу получить, используя код, который я создал ранее.
Используя эту информацию, я могу автоматически создать раздел, объясняющий, как импортировать компонент в проект:
И как использовать компонент:
Я также могу автоматически создать таблицу со всей необходимой информацией о свойствах:
Используйте все это
Теперь, когда у меня есть все различные части, я могу собрать их вместе, чтобы упростить создание документации компонента. Я начинаю с компонента, который я уже создал, и начинаю с установки того, что мне нужно:
npm i @el3um4s/svelte-get-component-info @el3um4s/svelte-component-infoПоэтому я создаю файл для управления созданием файла infoSvelteComponents.json с информацией:
Я обновляю файл package.json, добавляя несколько скриптов:
Я редактирую страницу документации компонента, импортируя InfoSvelte.svelte и файл json. Затем я добавляю компонент:
А потом… ничего, и все. Просто импортируйте компонент и файл JSON и ничего больше. Отныне всякий раз, когда я создаю документацию компонента с помощью npm run build, я буду автоматически импортировать всю обновленную информацию.
Как я уже сказал, работа над двумя репозиториями все еще продолжается. Я планирую обновить их в ближайшие несколько дней, но на данный момент я хотел привести в порядок различные шаги, предпринятые до сих пор.
Спасибо за прочтение! Оставайтесь с нами, чтобы узнать больше.
Не пропустите мою следующую статью — подпишитесь на мой Список адресов электронной почты среднего уровня
