Честно говоря, документация в Android не так болезненна с помощью таких инструментов, как Jetbrains Dokka, который помогает автоматически генерировать документацию для исходного кода Kotlin и Java или встроенного генератора JavaDoc в Android studio.
Хотя эти инструменты работают довольно хорошо, если вы такой же человек, как я, который явно мало разбирается в дизайне, то вы можете рассмотреть Orchid.
Orchid – это платформа для создания веб-сайтов с проектной документацией со всеми наворотами. Orchid позволяет вам публиковать все ваши вики-страницы, журналы изменений, блоги, комментарии к коду и даже выполнять развертывание. Он легко работает с Kotlin и Java-кодом.
В этом руководстве мы создадим базовый сайт документации для нашего проекта Android с помощью Orchid, включая документы Dokka code docs, wiki и развернем его на страницах Github.
Для краткого ознакомления вот примеры сайта документации, созданного с помощью Orchid.
Orchid, как и другие инструменты, собирает ваши комментарии KDoc или JavaDoc для создания вашей документации. Таким образом, это означает, что вы должны правильно прокомментировать свой код. Orchid будет собирать комментарии из классов, методов и свойств, а также выделять комментарии к параметрам, возврату и другим тегам.
Писать подобные комментарии довольно просто, просто введите \ ** и нажмите enter, Android studio автоматически сгенерирует остальное для вас.
СОВЕТ : Если вы используете Kotlin, все немного по-другому. Чтобы действительно воспользоваться помощью Android studio, вам необходимо установить плагин под названием Kdoc-generator.
Проще простого, это все, что нам нужно настроить, чтобы использовать Orchid. Все, что нам нужно сделать еще, это просто подключить Orchid для создания нашего красивого сайта документации.
Во-первых, нам нужно будет создать новый модуль, обязательно выберите библиотеку Java или Kotlin. Здесь будут находиться наши файлы Orchid, настройки и конфигурация. Назовите его доктора :
Вы можете наблюдать, как у нас теперь есть наш новый модуль docs .
Следующее, что нужно сделать, это открыть файл docs | build.gradle и добавить следующее:
plugins {
id "com.eden.orchidPlugin" version "0.21.0"
}
dependencies {
orchidRuntime "io.github.javaeden.orchid:OrchidDocs:0.21.0"
orchidRuntime "io.github.javaeden.orchid:OrchidKotlindoc:0.21.0"
orchidRuntime "io.github.javaeden.orchid:OrchidPluginDocs:0.21.0"
}
repositories {
jcenter()
maven { url = "https://kotlin.bintray.com/kotlinx/" }
}
orchid {
theme = "Editorial"
version = "1.0.0"
srcDir = "src/orchid/resources"
destDir = "build/docs/orchid"
}
Это добавляет плагин, загружает все необходимые зависимости Orchid и некоторую конфигурацию нашего сайта документации. Если вы посмотрите на блок orchid, вы увидите, что мы настроили некоторую базовую конфигурацию. тема : Мы будем использовать редакционную тему. Вы можете увидеть все доступные темы здесь . версия : Это ваша версия документации. srcDir : Здесь будут находиться все ваши ресурсы документации. дестДир : Здесь будут находиться все сгенерированные Orchid файлы.
Есть еще несколько вещей, которые нам нужно сделать, чтобы настроить wiki и указать ему, где найти наш код Kotlin, но вы можете запустить Orchid прямо сейчас с помощью |/.|gradlew:docs:orchidServe (опустить |/. | для Windows) и просмотреть сайт на/| http://localhost:8080 . Это должно дать вам результат, подобный следующему:
Теперь давайте начнем добавлять некоторый контент на нашу домашнюю страницу, содержимое которого записывается в формате markdown . Итак, давайте создадим файл с именем homepage.md в каталоге docs/src/orchid/resources/homepage.md нашего модуля docs и добавьте это:
// docs/src/orchid/resources/homepage.md # KotlinProject This is a short description of this project.
Теперь мы должны увидеть что-то вроде этого:
Здесь мы добавили наш первый файл homepage.md который содержит название и описание нашего сайта.
Orchid обрабатывает это с помощью файла config.yml . Итак, мы создадим его в нашем корневом каталоге здесь docs/src/orchid/resources/config.yml и добавим это:
# docs/src/orchid/resources/config.yml
site:
about:
siteName: Kotlin Project
siteDescription: This is a short description of this project.
Editorial:
primaryColor: '#DE9149'
social:
github: 'username/project'
По сути, в этом файле будут находиться настройки конфигурации нашего сайта. Он будет содержать код, который можно использовать для изменения общего внешнего вида нашего сайта. Вы можете видеть, что мы добавили About , который содержит название сайта и описание сайта. Кроме того, свойства, чтобы изменить настройки нашей редакционной темы и социальную ссылку. Это довольно прямолинейно. Мы можем поиграть с этими значениями и посмотреть, как происходят изменения.
Еще одна вещь, которую мы хотели бы сделать, – это связать наш файл readme. Вы можете разместить это на своей домашней странице. Чтобы сделать это, мы добавим раздел Front Matter в верхнюю часть файла домашней страницы и добавим компонент “Readme” на домашнюю страницу в этом Front Matter. Если вы ранее использовали Jekyll или другой генератор статических сайтов, Orchid обрабатывает Front Matter точно так же: YAML между парой строк с тройными тире. Кроме того, имейте в виду, что ваш файл readme должен находиться где-то в каталоге вашего проекта (модуль приложения).:
// docs/src/orchid/resources/homepage.md --- components: - type: 'pageContent' - type: 'readme' --- # Kotlin Project This is a short description of this project.
Автоматически Orchid подберет ваш файл readme и отобразит его на главной странице.
Следующее, что мы собираемся сделать, – это добавить несколько вики-файлов. Для этого нам нужно создать файл с именем summary.md в каталоге docs/src/orchid/resources/wiki/summary.md нашего модуля docs и добавьте это:
// docs/src/orchid/resources/wiki/summary.md - [Installation](installation.md) - [Basic Configuration](configuration.md) - [Features](features.md) - [Feature One](features/one.md) - [Feature Two](features/two.md) - [Extending](extending.md)
По сути, мы регистрируем каталог для наших вики-страниц, которых у нас нет. Я оставлю вас создавать эти файлы в вашем каталоге wiki. Каждый из них работает точно так же, как файл домашней страницы, и может содержать содержимое Markdown. Теперь, если вы посетите http://localhost:8080/wiki вы сможете начать навигацию по своей вики-странице. Одной из действительно приятных функций Orchid является встроенный статический поиск. Поэтому добавьте еще один компонент с именем orchid Search в наш файл config.yml :
# docs/src/orchid/resources/config.yml
site:
about:
siteName: Kotlin Project
siteDescription: This is a short description of this project.
Editorial:
primaryColor: '#DE9149'
legacySearch: false
social:
github: 'username/project'
metaComponents:
- type: 'orchidSearch'
Последнее, что нам нужно сделать, это начать настраивать меню вашего сайта и включить ссылку на эту вики-страницу. Вы можете сделать это в config.yml. Измените его, чтобы он выглядел следующим образом:
# docs/src/orchid/resources/config.yml
site:
about:
siteName: Kotlin Project
siteDescription: This is a short description of this project.
Editorial:
primaryColor: '#DE9149'
legacySearch: false
social:
github: 'username/project'
metaComponents:
- type: 'orchidSearch'
menu:
- type: 'separator'
title: 'Wiki'
- type: 'wiki'
Сейчас самое время сгенерировать наш документ API. Все, что нам нужно сделать сейчас, это просто обновить ваш файл config.yml, чтобы он указывал на наш исходный код. Добавьте это, чтобы сделать это:
# docs/src/orchid/resources/config.yml
kotlindoc:
sourceDirs:
- './../../../../app/src/main/java'
Здесь мы говорим Orchid найти наш исходный файл, где он будет генерировать наш документ API. Это, конечно, должно указывать на ваш модуль приложения. Как и другим, нам также нужно создать меню для нашего документа API, теперь просто обновите файл config.yml до этого:
# docs/src/orchid/resources/config.yml
site:
about:
siteName: Kotlin Project
siteDescription: This is a short description of this project.
Editorial:
primaryColor: '#DE9149'
legacySearch: false
social:
github: 'username/project'
metaComponents:
- type: 'orchidSearch'
menu:
- type: 'separator'
title: 'Wiki'
- type: 'wiki'
- type: 'page'
itemId: 'Changelog'
- type: 'separator'
title: 'API Docs'
- type: 'sourcedocPages'
moduleType: 'kotlindoc'
node: 'classes'
asSubmenu: true
submenuTitle: 'Classes'
- type: 'sourcedocPages'
moduleType: 'kotlindoc'
node: 'packages'
asSubmenu: true
submenuTitle: 'Packages'
Итак, у нас уже есть связанная документация по нашему API. Теперь мы можем легко перемещаться по созданному нами меню.
Поскольку наш сайт документации готов, пришло время его развернуть. Orchid предоставляет очень простой способ сделать это, все, что вам нужно сделать, это просто добавить некоторые настройки конфигурации в свой файл config.yml , и все в порядке.:
# docs/src/orchid/resources/config.yml
services:
publications:
stages:
ghPages:
branch: gh-pages
repo: 'project'
username: 'username'
Вам нужно будет заполнить необходимые данные по мере необходимости. Кроме того, нам нужно будет пройти аутентификацию с помощью Github, чтобы действительно успешно перейти в эту ветку. Чтобы сделать это, вам нужно создать Github Личный Доступ Token и установите его в переменную среды github Token. В вашем терминале…
export githubToken=...
И со всем этим док-сайт нашего Android-проекта готов! Хотя с помощью Orchid можно выполнить гораздо больше настроек, вот ссылка, чтобы погрузиться глубже .
Спасибо за чтение, пожалуйста, дайте мне знать, если я что-то пропустил или если у вас есть какие-либо советы по использованию Orchid!
Оригинал: “https://dev.to/weylar/generate-android-documentation-with-orchid-49p6”