Создание документации
Подобно команде crystal spec, о которой мы узнали в Главе 14 «Тестирование», существует также команда crystal docs. Наиболее распространенный сценарий генерации кода — в контексте сегмента. В этом случае все, что вам нужно сделать для создания документации, — это запустить crystal docs. Это обработает весь код в src/ и выведет сгенерированный веб-сайт в каталоге docs/ в корне проекта. Отсюда вы можете открыть docs/index.html в своем браузере, чтобы просмотреть созданный файл. Будущие вызовы crystal docs перезапишут предыдущие файлы.
Мы также можем передать этой команде явный список файлов; например, crystal docs one.cr two.cr three.cr. Это создаст документацию для кода внутри всех этих файлов или требуемую для них. Вы можете использовать это для включения внешнего кода в сгенерированную документацию. Например, предположим, что у вас есть проект, который зависит от двух других сегментов в том же пространстве имен. Вы можете передать основной файл точки входа для каждого проекта в crystal docs, в результате чего будет создан веб-сайт, содержащий документацию для всех трех проектов. Это будет выглядеть примерно так: crystal docs lib/project1/src/main.cr lib/project2/src/main.cr src/main.cr. Возможно, потребуется изменить порядок, чтобы он соответствовал требованиям project1 и project2 в src/main.cr.
Предоставление файлов для использования вручную требуется, если вы не используете команду в контексте сегмента, поскольку ни папка src/, ни файл shard.yml не существуют. Файл shard.yml используется для создания документации для определения названия проекта и его версии. Оба из них можно настроить с помощью опций --project-name и --project-version. Первое требуется, если оно не находится в контексте сегмента, а второе по умолчанию будет использовать имя текущей ветки с суффиксом -dev. Если вы не находитесь в контексте репозитория GitHub, его также необходимо указать явно.
Помимо создания HTML, эта команда также создает файл index.json, который представляет документацию в машиночитаемом формате. Это можно использовать для расширения/настройки способа отображения документации; например, https://mkdocstrings.github.io/crystal/index.html. Теперь, когда мы создали документацию, давайте потратим некоторое время на обсуждение того, что с ней делать, чтобы другие могли ее просмотреть. Мы также коснемся того, как управлять версиями документации по мере разработки вашего приложения.
Хостинг документации
Требовать, чтобы каждый пользователь создавал документацию для вашего проекта, далеко не идеально и мешает им просматривать его, что в конечном итоге приводит к меньшему принятию. Лучшим решением было бы разместить заранее созданную версию документации, чтобы пользователи могли легко ее найти и просмотреть.
Сгенерированная документация представляет собой полностью статический HTML, CSS и JavaScript, что позволяет размещать ее так же, как и любой веб-сайт, например, через Apache, Nginx и т. д. Однако для этих вариантов требуется сервер, к которому большинство людей, вероятно, не имеет доступа, исключительно для размещения HTML-документации. Распространенным альтернативным решением является использование https://pages. github.com/. Руководство о том, как это сделать, можно найти в справочном материале Crystaclass="underline" https://crystal-lang.org/reference/guides/hosting/github.html#hosting-your-docs-on-github-pages.
Управление версиями документации
Документацию, созданную для конкретной версии, больше никогда не нужно трогать. По этой причине в некоторых случаях может быть полезно опубликовать документацию для нескольких версий вашего приложения. Это особенно полезно, когда вы поддерживаете несколько версий вашего приложения, а не только последнюю.
Генератор документов имеет относительно простой встроенный переключатель версий, однако способы его использования не документированы. Суть в том, что при создании документации может быть предоставлен URL-адрес, указывающий на файл JSON, представляющий доступные версии, для включения раскрывающегося списка выбора версии.
Например, файл версий JSON для стандартной библиотеки можно найти по адресу https://Crystal-lang.org/api/versions.json. Содержимое файла представляет собой простой объект JSON с одним массивом версий, где каждый объект в массиве содержит имя версии и путь, по которому можно найти созданную для этой версии документацию.
Используя тот же URL-адрес, что и у файла версий Crystal, команда для создания документации будет выглядеть следующим образом: crystal docs –json-config-url=/api/versions.json.