Несколько месяцев назад я анонсировал первый проект SassDoc, инструмента документации для Sass. Какая длинная дорога прошла с тех пор. Пару дней назад мы наконец выпустили вторую основную версию SassDoc под названием Shiny Streamy Octopus . Мы работали над версией 2 в течение нескольких месяцев и провели несколько недель в бета-версии, позволяя талантливым людям протестировать наш продукт только для того, чтобы убедиться, что он достаточно хорош для выпуска. Ура!
У этой второй версии SassDoc есть две причины: первая — очистить кодовую базу. Я написал первый черновик SassDoc в середине 2014 года, и до тех пор мы работали над моим кодом. Хотя сам по себе код был неплохим, он, конечно, не очень масштабируемый, поэтому нам понадобилась гораздо более надежная база для будущего. К счастью, Валериан , Фабрис и Паскаль — три очень талантливых разработчика JavaScript, которые превратили мой старый дрянной код в великолепного зверя .
Вторая причина подтолкнуть SassDoc v2, и самая важная, состоит в том, чтобы создать прочную основу для создания новых функций. Таким образом, эта версия не приносит много новых функций. В основном он состоит из рефакторинга всей базы кода, исправления ошибок, улучшения API, устаревших функций и всего того дерьма, которое вы можете делать только в основных выпусках из-за разрывов API.
Так что, если бы я дал вам краткий обзор, а также несколько советов о том, как обновить SassDoc v1 до Shiny Streamy Octopus?
Новый брендинг
SassDoc начинался как эксперимент . В самом начале это была игровая площадка для меня, чтобы попробовать Node.js. Вскоре, это уже не был эксперимент, и реальные люди использовали его в реальных проектах, таких как ребята из ThoughtBot для Neat и Bourbon , а также внешние команды в The Guardian и Financial Times .
Поэтому мы решили дать брендингу немного любви к этой новой версии. Я перепроектировал весь сайт, чтобы иметь красивые документы. Мы разработали для нас логотип Reda Lemeden , а Аликс Лукас создал иллюстрацию, чтобы придать SassDoc некоторую визуальную силу.
При этом мы прекрасно понимаем, что не всем понравится новый брендинг. Это достаточно справедливо. Сайт не содержит ничего, кроме документации, и тему по умолчанию можно настроить. Если вам действительно не нравится тема по умолчанию, мы настроили все, чтобы вы могли создать свою собственную тему за пару минут.
Теперь, если вы чувствуете, что можете улучшить тему по умолчанию, мы с удовольствием объединим любой тщательный запрос на извлечение, так что не стесняйтесь сходить с ума и предлагать нам любые изменения!
API ломается
Давайте начнем с реальной вещи ™: разрывы API. Удивительно, но серьезных изменений в API не так много, как я думал вначале. В зависимости от вашего проекта, у вас может быть очень мало или ничего изменить в ваших файлах Sass для перехода на новую версию.
С-стиль не более
Я думаю, что самым большим изменением, которое мы сделали для конечного пользователя (то есть для вас) на этом этапе, было полное осуждение комментариев в стиле C. Вы знаете, как я использую для продажи SassDoc, говоря, что поддерживаются как комментарии в стиле C ( /** ... *//// Ну, это больше не правда. Мы решили, что предоставление двух способов написания документов сбивает с толку и мало чем поможет в конце дня. Кроме того, авторы библиотек, использующие комментарии в стиле C, загрязняют пользовательский код массивными блоками комментариев, что на самом деле не так круто.
Чтобы помочь перейти от стиля C к встроенным комментариям, наш собственный Валериан написал небольшой сценарий. Однако обратите внимание! Это необработанный поиск и замена, который не может быть на 100% пуленепробиваемым (на самом деле этот сценарий не может успешно преобразовать комментарии на уровне файлов из стиля C во встроенный). Обязательно внимательно изучите ваш код, чтобы убедиться, что все правильно.
Для GNU sed:
find . -name '*.s[ac]ss' -exec sed -i 's,^/\*\*,///,;s,^ *\*\*/,////,;s,^ *\*/,///,;s,^ *\*,///,' {} +
Для Mac / BSD sed:
find . -name '*.s[ac]ss' -exec sed -i ' 's,^/\*\*,///,;s,^ *\*\*/,////,;s,^ *\*/,///,;s,^ *\*,///,' {} +
Пользователям Windows, я предлагаю вам попробовать версию GNU в оболочке Git.
Взять значения в скобки по умолчанию
Еще одно важное изменение, которое, к сожалению, не может быть автоматически исправлено простым скриптом оболочки, — это использование скобок ( []()@property@parameter До этого вы бы написали что-то вроде этого:
/// @param {String} $foo ('bar') - Baz
Эта аннотация означает, что документированный элемент принимает аргумент $foo Это больше не работает. Отныне вы должны использовать скобки, превращая ваш код в:
bar
Выбор был немного сложным, но при использовании скобок в качестве оберток мы столкнулись с некоторыми проблемами при разборе. Подумайте о значениях по умолчанию, которые содержат скобки, например, вызовы функций (например, /// @param {String} $foo ['bar'] - Baz Время от времени наш парсер задыхался и не захватывал правильное значение. Короче говоря, мы решили пойти самым безопасным путем и использовать скобки.
Чтобы преобразовать эти скобки в скобки, Валериан (снова) написал небольшой сценарий. И снова, это фиктивный поиск и замена, поэтому обязательно внимательно изучите все, особенно потому, что скрипт преобразует length()(length($list)) Как я уже сказал, не пуленепробиваемый.
Для пользователя GNU:
[length[$list]]
Для пользователей Mac / BSD:
find . -type f -name '*.s[ac]ss' -exec sed -ri '/@param|@prop/y/()/[]/' {} +
Пользователям Windows, я предлагаю вам попробовать версию GNU в оболочке Git.
Папки вывода
Однажды, пару недель назад, мы пригласили кого-то на GitHub и сказали, что он стёр весь свой рабочий каталог. Дерьмо. Оказывается, он не читал вики (тогда у нас не было выделенного сайта), где мы предупреждали о стирании папки назначения при запуске SassDoc. Для его защиты это была не его вина полностью: мы не запрашивали и не прерывали, если папка назначения не была пустой. Я считаю, что мы все испортили.
Вскоре после этого мы выдвинули что-то с флагами, чтобы заставить / подсказать вам это. Это работало лучше, это предотвращало любые инциденты, это делало API немного более сложным. Таким образом, мы пошли очень простым путем, который я давно отбросил, потому что он мне не очень понравился: мы сделали так, чтобы SassDoc всегда выводил свой собственный каталог ( find . -type f -name '*.s[ac]ss' -exec sed -Ei ' '/@param|@prop/y/\(\)/\[\]/' {} +./sassdoc
Итак, теперь использование SassDoc стало намного проще. CLI API запрашивает только исходную папку. Папка назначения может быть установлена с --dest--dest
Чтобы задокументировать конкретную папку, например ./sassdoc Чтобы изменить путь к папке назначения, такой как stylesheets/docs/sass/
--dest
Новые особенности
Я сказал, что эта версия, по сути, была основным рефакторингом API, но мы, очевидно, использовали ее как возможность для введения новых незначительных функций.
Более мощный API
В предыдущем разделе мы видели, как мы настраивали API, чтобы сделать все немного более надежным (особенно в отношении выходной папки). Вам будет приятно узнать, что мы также позволили вам определить шаблоны исключений, чтобы вы могли запретить SassDoc анализировать некоторые файлы и / или папки.
Например, вы можете использовать SassDoc для анализа вашей папки стилей, но не использовать таблицы стилей поставщиков. Используя только CLI API, это выглядело бы так (цитаты важны):
sassdoc stylesheets/ --dest ./docs/sass/
Теперь вы можете использовать файл конфигурации для более постоянной настройки, например:
sassdoc stylesheets/ '!stylesheets/vendors/*'
В том же духе теперь можно передавать поток в SassDoc. Проще говоря, теперь вы можете запустить SassDoc для файла из консоли. Например:
exclude:
- ./stylesheets/vendors/*
Это облегчает отладку документированного файла Sass, особенно при использовании его в сочетании с флагом cat stylesheets/utils/_functions.scss | sassdoc -
--parse
Вы даже можете запустить его на файле, который не находится на вашем компьютере, используя cat stylesheets/utils/_functions.scss | sassdoc --parse - Например, с файлом, размещенным на GitHub:
curl
Говоря об отладке, мы ввели параметр curl https://raw.githubusercontent.com/SassDoc/sassdoc-theme-default/master/scss/utils/_functions.scss | sassdoc --parse - Особенно полезно при открытии проблемы в хранилище: просто поместите след, напечатанный --debug
--debug
Лучшая тема по умолчанию
Мы также вкладываем много любви в тему по умолчанию, чтобы максимально улучшить ее. Одна важная функция, которую мы добавили, — это возможность использовать Google Analytics или любую другую систему отслеживания в созданных документах. Для этого мы » [DEBUG] argv: ["scss/","--debug"]
» [DEBUG] process.argv: ["node","/Users/admin/Documents/projects/sassdoc/sassdoc/bin/sassdoc","scss/","--debug"]
» [DEBUG] sassdoc version: 2.0.3
» [DEBUG] node version: 0.10.33
» [DEBUG] npm version: 2.1.9
» [DEBUG] platform: darwin
» [DEBUG] cwd: /Users/admin/Documents/projects/sassdoc/sassdoc-theme-default
» [DEBUG] env: {
"strict": false,
"file": ".sassdocrc",
"dest": "sassdoc",
"dir": "/Users/admin/Documents/projects/sassdoc/sassdoc-theme-default",
"package": {},
"themeName": "default",
"src": [
"scss/"
]
}
» [DEBUG] task: documentize
» [DEBUG] Dumping data to `sassdoc-data.json`.googleAnalyticstrackingCode
Свойство googleAnalytics — это просто ключ отслеживания Google Analytics, сопоставленный с вашим сайтом. Тема напечатает соответствующий фрагмент JavaScript с вашим ключом, чтобы вы могли отслеживать GA.
googleAnalytics: UA-XXXXX-YY
Кроме того, опция trackingCode также помогает добавить в ваши документы какую-либо систему отслеживания, за исключением того, что она немного более разрешающая. По сути, это какой-то HTML, который печатается прямо перед закрытием тег. Остерегайтесь того, что вы положили туда, конечно.
trackingCode: |
<img src="http://piwik.example.org/piwik.php?idsite={$IDSITE}amp;rec=1" style="border:0" alt="" />
Что дальше?
Мы заморозили набор функций SassDoc за несколько недель до запуска версии 2, чтобы сосредоточиться на рефакторинге всего, не мешая новым разработкам. Теперь, когда вышел Shiny Streamy Octopus, мы можем вернуться к реализации новых функций, и у нас было много предложений. Среди других:
- Добавить возможность представить документы с кратким и длинным отрывком ( # 256 ).
- Добавить возможность определять несколько групп для одного и того же элемента, а также вложенные группы ( # 135 ).
- Добавить возможность переопределить имя элемента с помощью аннотации
@name# 296 ). - Добавлена возможность упорядочивать элементы по
@access# 239 ). - Добавьте опцию, чтобы предположить, что элемент является личным, если он начинается с
_-# 340 ). - Автозаполнение других вещей, таких как значения по умолчанию ( # 304 ).
- Разрешить наследование темы и подтемы ( # 272 ).
Я думаю, что мы увидим еще много предложений в ближайшие несколько недель. Конечно, мы очень ценим обратную связь, поэтому, если у вас есть что рассказать, обязательно сделайте это.
Хотя позвольте мне использовать эту статью как возможность заявить, что SassDoc все еще не планирует превращаться в полноценную систему документации. Таким образом, SassDoc не может документировать селекторы CSS, и мы не планируем добавлять эту функцию в ближайшее время (возможно, в v3 ).
SassDoc намеревается документировать Sass API и проекты. Мы делаем эту единственную вещь, но мы очень стараемся сделать это правильно. Я думаю, что у нас все еще есть большой прогресс в этой области, прежде чем перейти к такой большой вещи, как селекторы CSS.
В любом случае, обязательно посмотрите журнал изменений для версии 2 и официальный сайт, чтобы прочитать документацию. Конечно, мы готовы ответить на любой ваш вопрос в Твиттере; просто пинг @SassDoc_ или я сам!