diff --git a/ru/about.md b/ru/about.md index c94470f..fe0c13d 100644 --- a/ru/about.md +++ b/ru/about.md @@ -7,15 +7,26 @@ Diplodoc - это платформа работы с документацией ## Достоинства платформы: ### Простота использования + Работа с документами как с кодом: в привычной среде и с минимальными усилиями по развёртыванию и поддержке. + ### Cкорость работы + Быстрая сборка, валидация и выкладка документации любого размера. Полная интеграция в существующие CI/CD-системы для ускорения работы. + ### Общепринятый формат Markdown + Простой, понятный и широко распространенный синтаксис с поддержкой базового Markdown. Концентрируйтесь на контенте, а не на том, как доставить его до пользователя. + ### Обширная функциональность + Создание документов любой сложности, в том числе генерация из единого источника и работа с переменными. Широкие возможности по кастомизации и отображению гарантируют удовлетворённость конечных пользователей. + ### Интеграция с системами автоматической документации + Поддержка широко распространённой OpenAPI-спецификации «из коробки». Обеспечение работы специализированных систем через интерфейс подключаемых внешних документов. + ### Поиск + Самый частотный пользовательский сценарий по поиску документов на базе платформы без дополнительных затрат и усилий по поддержке. diff --git a/ru/features.md b/ru/features.md index 7c42f0c..8354ce3 100644 --- a/ru/features.md +++ b/ru/features.md @@ -1 +1,23 @@ -# Функциональные возможности \ No newline at end of file +# Функциональные возможности + +## Работа в парадигме Docs as code + +Документация разрабатывается с помощью привычных инструментов разработчика. Используйте расширенный диалект Markdown и отслеживайте изменения с помощью системы контроля версий. + +## Предварительный просмотр изменений + +Проверяйте изменения на тестовых хостах в каждом пулл-реквесте. + +Поддерживается в репозиториях GitHub и GitLab. + +## Интеграция и автоматизация + +Diplodoc поддерживает интеграцию с СI/CD системами – требуется включение [Builder](tools/docs/index.md) для срабатывания по триггерам обновления документации в репозитории. + +Как для С++ или Java проектов используются специальные компиляторы в пайплайнах, так для документации эта задача выполняется Builder'ом. Он создает готовые документы (артефакты), которые потом можно автоматически разместить на внутренних или внешних ресурсах для пользователей. + +### Публикация на собственном домене или на diplodoc.com + +Если ваш проект использует Github как систему контроля версий и место хранения исходного кода вашей документации, Diplodoc позволит создать полностью интегрированный пайплайн работы, покрывающий все шаги от внесения изменений в исходные тексты до построения проекта с помощью Github actions и интеграции с Elastic Search. + +[Свяжитесь с нами](https://diplodoc.com/#contact), чтобы обсудить детали вашей конфигурации и возможные варианты решения. diff --git a/ru/github-pages.md b/ru/github-pages.md new file mode 100644 index 0000000..f29ce61 --- /dev/null +++ b/ru/github-pages.md @@ -0,0 +1,21 @@ +# Публикация на GitHub Pages + +1. В GitHub в репозитории вашего документа перейдите на вкладку **Settings** и в меню слева выберите **Pages**. + +1. В разделе **Build and deployment** в выпадающем списке выберите **GitHub Actions** и в появившемся блоке **Static HTML** нажмите кнопку **Configure**. Откроется окно редактирования экшна. + +1. В блоке `jobs` после строки `uses: actions/configure-pages@v5` добавьте код + + ```yaml + - name: Build docs + uses: diplodoc-platform/docs-build-action@v3 + with: + src-root: './docs' + build-root: './docs-html' + ``` + +1. Вверху справа нажмите **Commit changes...**, укажите имя коммита в поле **Commit message** и нажмите кнопку **Commit changes**. + +1. Перейдите на вкладку **Actions**. Вверху списка будет ваш последний коммит. + +1. Нажмите на название коммита. После завершения сборки, документ будет размещен на GitHub Pages. Посмотреть его можно по ссылке ниже под надписью **deploy**. \ No newline at end of file diff --git a/ru/how-it-work.md b/ru/how-it-work.md index 05206f6..a7ea730 100644 --- a/ru/how-it-work.md +++ b/ru/how-it-work.md @@ -71,16 +71,6 @@ yfm -i ./input-folder -o ./ouput-folder Готовые проекты в HTML можно использовать локально или разместить на подходящем для Вас хостинге, включая S3-like хранилище. -## Интеграция в ваш процесс разработки - -### Создание и построение проекта - -В общем случае структура проекта и процедуры построения не отличаются от описанного в предыдущем разделе. -В случае интеграции с вашими СI/CD пайплайнами требуется включение Builder для срабатывания по триггерам обновления документации в репозитории. - -Как для С++ или Java проектов используются специальные компиляторы в пайплайнах, так для документации эта задача выполняется Builder'ом. Он создает готовые документы (артефакты), которые потом можно автоматически разместить на внутренних или внешних ресурсах для пользователей. - - ### Подключение плагинов и расширенная конфигурация Как правило, большие документационные проекты используют дополнительные возможности по работе с контентом и специфичные конфигурации для построения. @@ -91,31 +81,3 @@ yfm -i ./input-folder -o ./ouput-folder Особенностью конфигурации при построении может быть возможность отключения линтера или сборка проекта в виде одного большого HTML-файла. Дополнительно с такими возможностями можно ознакомиться на [странице](./tools/transform/settings.md). - -## Работа с Github и публикация документов на своем домене или домене https://diplodoc.com - -Если ваш проект использует Github как систему контроля версий и место хранения исходного кода вашей документации, Diplodoc позволит создать полностью интегрированный пайплайн работы, покрывающий все шаги от внесения изменений в исходные тексты до построения проекта с помощью Github actions и интеграции с Elastic Search. - -[Свяжитесь с нами](https://diplodoc.com/#contact), чтобы обсудить детали вашей конфигурации и возможные варианты решения. - -### Размещение документа на GitHub Pages - -1. В GitHub в репозитории вашего документа перейдите на вкладку **Settings** и в меню слева выберите **Pages**. - -1. В разделе **Build and deployment** в выпадающем списке выберите **GitHub Actions** и в появившемся блоке **Static HTML** нажмите кнопку **Configure**. Откроется окно редактирования экшна. - -1. В блоке `jobs` после строки `uses: actions/configure-pages@v5` добавьте код - - ```yaml - - name: Build docs - uses: diplodoc-platform/docs-build-action@v3 - with: - src-root: './docs' - build-root: './docs-html' - ``` - -1. Вверху справа нажмите **Commit changes...**, укажите имя коммита в поле **Commit message** и нажмите кнопку **Commit changes**. - -1. Перейдите на вкладку **Actions**. Вверху списка будет ваш последний коммит. - -1. Нажмите на название коммита. После завершения сборки, документ будет размещен на GitHub Pages. Посмотреть его можно по ссылке ниже под надписью **deploy**. diff --git a/ru/index.yaml b/ru/index.yaml index b80fb20..ddc8719 100644 --- a/ru/index.yaml +++ b/ru/index.yaml @@ -4,15 +4,9 @@ meta: title: Метаданные noIndex: true links: -- title: Обзор системы - description: Описание платформы, ее основные возможности, особенности и преимущества. +- title: О платформе + description: Описание платформы, ее особенности и преимущества. href: about.md -- title: Быстрый старт - description: С чего начать работу - href: how-it-work.md -- title: Yandex Flavored Markdown - description: Описание языка Yandex Flavored Markdown. - href: index-yfm.md - - - +- title: Возможности платформы + description: Функциональные возможности Diplodoc + href: features.md diff --git a/ru/toc.yaml b/ru/toc.yaml index be19035..c7bc512 100644 --- a/ru/toc.yaml +++ b/ru/toc.yaml @@ -117,11 +117,13 @@ items: href: project/pc-example2.yaml - name: Пример 3 (fullScreen mode) href: project/pc-example3.yaml - - name: Конфигурация проекта + - name: Деплой и конфигурация проекта labeled: true items: - name: Настройки проекта href: settings.md + - name: Github Pages + href: github-pages.md - name: Внесение изменений href: contribution.md - name: Практические руководства