From c01c9f3de2cc4295456ab1462501e4a7b6036167 Mon Sep 17 00:00:00 2001 From: Dmitry Date: Thu, 14 Nov 2024 23:59:00 +0600 Subject: [PATCH 1/3] DOCSUP-86795 --- ru/guides/openapi.md | 193 +++++++++++++++++++++++++++++++++++++++++++ ru/toc.yaml | 2 + 2 files changed, 195 insertions(+) create mode 100644 ru/guides/openapi.md diff --git a/ru/guides/openapi.md b/ru/guides/openapi.md new file mode 100644 index 0000000..0415725 --- /dev/null +++ b/ru/guides/openapi.md @@ -0,0 +1,193 @@ +# Генерация из OpenAPI-спецификации + +Вы можете сгенерировать документ из [OpenAPI-спецификации](https://www.openapis.org/) и включить её в основной документ. + +{% note warning %} + +Openapi-инклюдер требует разрешение на использование HTML в документации, поэтому внутри конфигурационного файла `.yfm` необходимо указать значение `allowHTML: true`. + +{% endnote %} + +## Требования к OpenAPI-спецификации + +- Версия используемой спецификации не ниже 3.Х. +- Допускается использование только операторов `oneOf` и `allOf`. +- Ограничения на использование базового функционала не накладываются. + +## Пример использования + +1. Документационный проект лежит в директории `doc_root`. + +2. OpenAPI-спецификацию размещаем по пути `doc_root/openapi.yaml`. + +3. Включаем её в оглавление `doc_root/toc.yaml` с помощью [openapi-инклюдера](https://diplodoc.com/docs/ru/project/toc#includers). + +4. Подключаем разводящую в `doc_root/index.yaml`. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: + - name: openapi + include: + path: openapi + includers: + - name: openapi + input: openapi.yaml + mode: link +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: openapi + href: openapi/ +``` + + +### `tags` + +Позволяет менять оглавления тегов. Описания конечных точек, полученные после сборки, раскладываются по тегам. + +#### Синтаксис + +```yaml +tags: + __root__: + name: Новое название оглавления на верхнем уровне + path: hello.md + alias: 'new-url-path' + hidden: false + tag: + name: Название оглавления внутри тега tag + path: custom.md + alias: 'new-tag' + hidden: true +``` + +Параметр `tag` принимает описания тегов: + +* `name` - меняет отображаемое на сайте имя оглавления. + +* `path` - записывает в оглавление любой контент. Путь до файла с новым содержимым указыватеся относительно файла с конфигурацией OpenAPI. + +* `alias` - меняет путь до файла. Все теги на русском языке преобразуются в транслит. С помощью это поля можно указывать произвольное имя файла. Например, есть тег "Регистрация пользователя". Если его не изменить, ссылка на раздел будет выглядеть так `doc.com/registracia_polzovatelya`. Если указать `alias: registration`, ссылка будет иметь вид `doc.com/registration`. + +* `hidden` - скрывает раздел оглавления из навигации. + +Оглавление верхнего уровня можно настроить с момощью тега `__root__`. + +### `leadingPage` + +Позволяет настроить все оглавления за раз. + +#### Синтаксис + +```yaml + leadingPage: + name: Новое имя всех оглавлений + spec: + renderMode: hidden +``` +Теги: + +* `name` - меняет название всех оглавлений. +* `spec.renderMode` - определяет, нужно ли добавлять OpenAPI-спецификацию в оглавление. Если да, необходимо указать значение `renderMode: inline`, в ином случае - `renderMode: hidden`. + +### `sandbox` + +Позволяет отобржать таб с песочницей, через которую можно отправлять запросы. + +#### Синтаксис + +```yaml +sandbox: + tabName: Название таба с песочницей + host: 'https://sandox.doc.ru' +``` + +## Скрытие полей + +```yaml +x-hidden: true +``` +Чтобы скрыть параметры операции или поля объекта, добавьте в их описание `x-hidden: true`. + +Пример. + +```yaml +- name: example + required: false + schema: + type: string + description: "Пример" + x-hidden: "true" +``` + +## Скрытие описаний + +Существует 3 вида фильтрации: + +* `filter`; +* `nobuild`; +* `noindex`. + +Они имеют общий интерфейс фильтрации: + +```yaml +filter: + endpoint: tags contains "nobuild" != true + tag: name == "noindex" +``` + +Поле `endpoint` позволяет пометить конечную точку определенным свойством (зависит от выбранного режима фильтрации) аналогично тому, как поле `tag` помечает теги. + +### `filter` + +Позволяет указать условие, определяющее нужно ли добавлять конечную точку в сборку. + +#### Синтаксис + +```yaml + filter: + endpoint: tags contains "nobuild" != true +``` + +#### Пример использования + +Необходимо, чтобы незавершенные описания не попали в документацию. Чтобы получить такой результат: + +1. Добавьте каждому описанию тег `nobuild` (можно использовать любой тег, но для простоты принято добавлять именно этот). + +2. Добавьте фильтр на этот тег: + + ```yaml + filter: + endpoint: tags contains "nobuild" != true + ``` +В результате работы фильтра в документации не будет ненужных страниц. + +### `noindex` + +Позволяет написать условие, определяющее, будет ли описание индексироваться поисковыми роботами. + +#### Синтаксис + +```yaml +noindex: + tag: name == "noindex" +``` + +#### Пример использования + +Необходимо скрыть описание от поисковых роботов. Чтобы получить такой результат: + +1. Добавьте каждому описанию тег `noindex` (можно использовать любой тег, но для простоты принято добавлять именно этот). +2. Добавьте фильтр на этот тег: + + ```yaml + noindex: + tag: name == "noindex" + ``` diff --git a/ru/toc.yaml b/ru/toc.yaml index e22e2b3..63330f8 100644 --- a/ru/toc.yaml +++ b/ru/toc.yaml @@ -152,6 +152,8 @@ items: items: - name: Контентная аналитика href: guides/content-analytics.md + - name: Генерация из OpenAPI-спецификации + href: guides/openapi.md - name: Вакансии hidden: true items: From 939668afcc3bf5a414cd1d50c09382cd235d850e Mon Sep 17 00:00:00 2001 From: Dmitry Date: Fri, 15 Nov 2024 00:21:30 +0600 Subject: [PATCH 2/3] =?UTF-8?q?=D0=B8=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D1=8F=20=D0=BF=D0=BE=20=D1=82=D0=B5=D0=BA?= =?UTF-8?q?=D1=81=D1=82=D1=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ru/guides/openapi.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ru/guides/openapi.md b/ru/guides/openapi.md index 0415725..4b5c114 100644 --- a/ru/guides/openapi.md +++ b/ru/guides/openapi.md @@ -14,7 +14,7 @@ Openapi-инклюдер требует разрешение на использ - Допускается использование только операторов `oneOf` и `allOf`. - Ограничения на использование базового функционала не накладываются. -## Пример использования +#### Пример использования 1. Документационный проект лежит в директории `doc_root`. @@ -105,7 +105,7 @@ tags: ```yaml sandbox: tabName: Название таба с песочницей - host: 'https://sandox.doc.ru' + host: 'https://sandbox.doc.ru' ``` ## Скрытие полей @@ -115,7 +115,7 @@ x-hidden: true ``` Чтобы скрыть параметры операции или поля объекта, добавьте в их описание `x-hidden: true`. -Пример. +#### Пример использования ```yaml - name: example From 5fbb12c3dfc5a6339cc25cd6e703cf46451b82ab Mon Sep 17 00:00:00 2001 From: Dmitry Date: Tue, 26 Nov 2024 01:44:22 +0600 Subject: [PATCH 3/3] =?UTF-8?q?=D0=BF=D0=B5=D1=80=D0=B5=D0=B5=D0=B7=D0=B4?= =?UTF-8?q?=20includers=20=D0=B8=D0=B7=20toc=20=D0=B2=20=D1=80=D0=B0=D0=B7?= =?UTF-8?q?=D0=B4=D0=B5=D0=BB=20guides?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ru/changelog.md | 12 +-- ru/guides/generic.md | 37 +++++++ ru/guides/includers.md | 57 ++++++++++ ru/guides/openapi.md | 2 +- ru/guides/source-docs.md | 39 +++++++ ru/guides/unarchive.md | 42 ++++++++ ru/project/toc.md | 222 +-------------------------------------- ru/toc.yaml | 13 ++- 8 files changed, 195 insertions(+), 229 deletions(-) create mode 100644 ru/guides/generic.md create mode 100644 ru/guides/includers.md create mode 100644 ru/guides/source-docs.md create mode 100644 ru/guides/unarchive.md diff --git a/ru/changelog.md b/ru/changelog.md index 37c20e5..8e186e8 100644 --- a/ru/changelog.md +++ b/ru/changelog.md @@ -10,11 +10,11 @@ noindex: true #### 2.0.0 -- [Новый интерфейс инклюдеров](./project/toc.md#includers). -- [Generic инклюдер](./project/toc.md#includers-generic). -- [Open API инклюдер](./project/toc.md#includers-open-api). -- [Unarchive инклюдер](./project/toc.md#includers-unarchive). -- [Source Docs инклюдер](./project/toc.md#includers-source-docs). +- [Новый интерфейс инклюдеров](./guides/includers.md). +- [Generic инклюдер](./guides/generic.md). +- [Open API инклюдер](./guides/openapi.md). +- [Unarchive инклюдер](./guides/unarchive.md). +- [Source Docs инклюдер](./guides/source-docs.md). ## Ноябрь 2022 @@ -82,7 +82,7 @@ noindex: true - include/includers: возможность интеграции сторонних форматов в документацию. - include/includers/sourcedocs: возможность интеграции sourcedocs документации в yfm-документацию. - [Includers](./project/toc.md#includers) + [Includers](./guides/includers.md) ## Июнь 2022 diff --git a/ru/guides/generic.md b/ru/guides/generic.md new file mode 100644 index 0000000..38010ce --- /dev/null +++ b/ru/guides/generic.md @@ -0,0 +1,37 @@ +# Generic + +Вы можете сгенерировать документацию в markdown-формате любой утилитой и включить её в основную документацию. + +Инклюдер сгенерирует по ней оглавление и включит контент в документацию. + +#### Пример использования + +Проект документации лежит в `doc_root` папке. + +Положим сгенерированный контент в папку `doc_root/docs`. + +Включим этот контент с помощью generic-инклюдера в `doc_root/toc.yaml`. + +Подключим разводящую в `doc_root/index.yaml`. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: + - name: docs + include: + path: docs + includers: + - name: generic + input: docs + mode: link +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: docs + href: docs/ +``` diff --git a/ru/guides/includers.md b/ru/guides/includers.md new file mode 100644 index 0000000..894ba16 --- /dev/null +++ b/ru/guides/includers.md @@ -0,0 +1,57 @@ +# Вставка произвольного контента (Includers) + +Вы можете включить в оглавление произвольный контент через `includers`, но только в случае если `includer` для этого типа контента имплементирован. Список имплементированных инклюдеров можно посмотреть [ниже](#implement-includers). + +Возможные способы указания инклюдеров: + +- массив `includer`-объектов в поле `includers`; + +- `includer`-объект в поле `includer` (_в процессе деприкации в пользу `includers` поля_). + +**Требования к `include`:** + +1. `include` должен иметь поле `path`, куда контент будет включен. + +2. поле `path` должно быть **путем, куда будет включен контент**. + +3. свойство `mode` должно иметь значение `link или пропущенно, `link является дефолтным поведением. + +**Требования к `includers`:** + +`includers` должен быть массивом includer-объектов, которые будут запущенны в указанном порядке. + +**Требования к `includer`:** + +Параметры между includer-объектами разные, но имя `includer` является обязательным параметром. + +`name` указывает имя инклюдера, который запустится. + + +#### Пример использования + +Абстрактный пример использования инклюдеров + +_Уточненный пример смотрите в разделе соответствуещего инклюдера для конкретного примера использования._ + +``` +# toc.yaml +... +items: + - name: + include: + path: + includers: + - name: + : + - name: + - name: + mode: link +... +``` + +## Список имплементированных инклюдеров {#implement-includers} + +- [Generic](generic.md); +- [Open API](openapi.md); +- [Unarchive](unarchive.md); +- [Source Docs](source-docs.md) (_в процессе деприкации в пользу generic инклюдера_). \ No newline at end of file diff --git a/ru/guides/openapi.md b/ru/guides/openapi.md index 4b5c114..05eb205 100644 --- a/ru/guides/openapi.md +++ b/ru/guides/openapi.md @@ -20,7 +20,7 @@ Openapi-инклюдер требует разрешение на использ 2. OpenAPI-спецификацию размещаем по пути `doc_root/openapi.yaml`. -3. Включаем её в оглавление `doc_root/toc.yaml` с помощью [openapi-инклюдера](https://diplodoc.com/docs/ru/project/toc#includers). +3. Включаем её в оглавление `doc_root/toc.yaml` с помощью [openapi-инклюдера](includers.md). 4. Подключаем разводящую в `doc_root/index.yaml`. diff --git a/ru/guides/source-docs.md b/ru/guides/source-docs.md new file mode 100644 index 0000000..f2afee6 --- /dev/null +++ b/ru/guides/source-docs.md @@ -0,0 +1,39 @@ +# Source Docs + +Вы можете включить документацию в формате [Source Docs](https://github.com/SourceDocs/SourceDocs) в основной документ. + +{% note warning %} + +sourcedocs-инклюдер находится в процессе деприкации в пользу [generic-инклюдера](generic.md). + +{% endnote %} + +#### Пример использования + +Проект документации лежит в папке `doc_root`. + +Положим результат исполнения Source Docs в папку `doc_root/docs`. + +Включим его в документацию внутри `doc_root/toc.yaml`, указав `includer` sourcedocs. + +Поставим ссылку на сгенерированную разводящую в основной в `doc_root/index.yaml`. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: + - name: docs + include: + path: docs + includer: sourcedocs + mode: link +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: docs + href: docs/ +``` diff --git a/ru/guides/unarchive.md b/ru/guides/unarchive.md new file mode 100644 index 0000000..d53d181 --- /dev/null +++ b/ru/guides/unarchive.md @@ -0,0 +1,42 @@ +# Unarchive + +Вы можете использовать unarchive-инклюдер чтобы распаковать tarball перед тем как применять другие инклюдеры к контенту внутри него, например generic-инклюдер. + +#### Пример использования + +Есть `docs.tar` в корне проекта по пути `doc_root/docs.tar`. + +Внутри `docs.tar` находится контент, который необходимо включить используя generic-инклюдер. + +В этом случае нужно применить цепь инклюдеров `unarchive` -> `generic` для достижения цели. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: +... + - name: multiple + include: + path: multiple + mode: link + includers: + # run unarchive includer + - name: unarchive + # specify tarball you want to unpack as input parameter + input: docs.tar + # specify output path where tarball content is going to be unpacked + output: unpacked + # run generic includer + - name: generic + # specify path from unarchive includers output field as input path + input: unpacked +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: openapi + href: openapi/ +``` diff --git a/ru/project/toc.md b/ru/project/toc.md index e656e42..58df173 100644 --- a/ru/project/toc.md +++ b/ru/project/toc.md @@ -204,224 +204,6 @@ items: - include: { mode: merge, path: ../relative/path/to/toc.yaml } ``` -### Вставка произвольного контента (Includers) {#includers} - -Вы можете включить в оглавление произвольный контент через `includers`, но только в случае если `includer` для этого типа контента имплементирован. Список имплементированных инклюдеров можно посмотреть [ниже](#implement-includers). - -Возможные способы указания инклюдеров: - -- массив `includer`-объектов в поле `includers`; - -- `includer`-объект в поле `includer` (_в процессе деприкации в пользу `includers` поля_). - -**Требования к `include`:** - -1. `include` должен иметь поле `path`, куда контент будет включен. - -2. поле `path` должно быть **путем, куда будет включен контент**. - -3. свойство `mode` должно иметь значение `link или пропущенно, `link является дефолтным поведением. - -**Требования к `includers`:** - -`includers` должен быть массивом includer-объектов, которые будут запущенны в указанном порядке. - -**Требования к `includer`:** - -Параметры между includer-объектами разные, но имя `includer` является обязательным параметром. - -`name` указывает имя инклюдера, который запустится. - - -#### Пример использования - -Абстрактный пример использования инклюдеров - -_Уточненный пример смотрите в разделе соответствуещего инклюдера для конкретного примера использования._ - -``` -# toc.yaml -... -items: - - name: - include: - path: - includers: - - name: - : - - name: - - name: - mode: link -... -``` - -#### Список имплементированных инклюдеров {#implement-includers} - -- [Generic](#includers-generic); -- [Open API](#includers-open-api); -- [Unarchive](#includers-unarchive); -- [Source Docs](#includers-source-docs) (_в процессе деприкации в пользу generic инклюдера_). - -#### Generic {#includers-generic} - -Вы можете сгенерировать документацию в markdown-формате любой утилитой и включить её в основную документацию. - -Инклюдер сгенерирует по ней оглавление и включит контент в документацию. - -**Пример использования:** - -Проект документации лежит в `doc_root` папке. - -Положим сгенерированный контент в папку `doc_root/docs`. - -Включим этот контент с помощью generic-инклюдера в `doc_root/toc.yaml`. - -Подключим разводящую в `doc_root/index.yaml`. - -```yaml -# doc_root/toc.yaml -title: documentation -href: index.yaml -items: - - name: docs - include: - path: docs - includers: - - name: generic - input: docs - mode: link -``` - -```yaml -# doc_root/index.yaml -title: documentation -links: - - title: docs - href: docs/ -``` - -#### Open API {#includers-open-api} - -Вы можете сгенерировать документ из [OpenAPI-спецификации](https://www.openapis.org/) и включить её в основной документ. - -{% note warning %} - -Openapi-инклюдер требует разрешение на использование HTML в документации, поэтому внутри конфигурации `.yfm` укажите значение `allowHTML: true`. - -{% endnote %} - -**Пример использования:** - -Проект документации лежит в `doc_root`. - -Положим openAPI-спецификацию по пути `doc_root/openapi.yaml`. - -Включим её в `doc_root/toc.yaml` с помощью openapi-инклюдера. - -Подключим разводящую в `doc_root/index.yaml`. - -```yaml -# doc_root/toc.yaml -title: documentation -href: index.yaml -items: - - name: openapi - include: - path: openapi - includers: - - name: openapi - input: openapi.yaml - mode: link -``` - -```yaml -# doc_root/index.yaml -title: documentation -links: - - title: openapi - href: openapi/ -``` - -#### Unarchive {#includers-unarchive} - -Вы можете использовать unarchive-инклюдер чтобы распаковать tarball перед тем как применять другие инклюдеры к контенту внутри него, например generic-инклюдер. - -**Пример использования:** - -Есть `docs.tar` в корне проекта по пути `doc_root/docs.tar`. - -Внутри `docs.tar` находится контент, который необходимо включить используя generic-инклюдер. - -В этом случае нужно применить цепь инклюдеров `unarchive` -> `generic` для достижения цели. - -```yaml -# doc_root/toc.yaml -title: documentation -href: index.yaml -items: -... - - name: multiple - include: - path: multiple - mode: link - includers: - # run unarchive includer - - name: unarchive - # specify tarball you want to unpack as input parameter - input: docs.tar - # specify output path where tarball content is going to be unpacked - output: unpacked - # run generic includer - - name: generic - # specify path from unarchive includers output field as input path - input: unpacked -``` - -```yaml -# doc_root/index.yaml -title: documentation -links: - - title: openapi - href: openapi/ -``` - -#### Source Docs - -Вы можете включить документацию в формате [Source Docs](https://github.com/SourceDocs/SourceDocs) в основной документ. - -{% note warning %} - -sourcedocs-инклюдер находится в процессе деприкации в пользу [generic-инклюдера](#includers-generic). - -{% endnote %} - -##### Пример использования - -Проект документации лежит в папке `doc_root`. - -Положим результат исполнения Source Docs в папку `doc_root/docs`. - -Включим его в документацию внутри `doc_root/toc.yaml`, указав `includer` sourcedocs. - -Поставим ссылку на сгенерированную разводящую в основной в `doc_root/index.yaml`. - -```yaml -# doc_root/toc.yaml -title: documentation -href: index.yaml -items: - - name: docs - include: - path: docs - includer: sourcedocs - mode: link -``` - -```yaml -# doc_root/index.yaml -title: documentation -links: - - title: docs - href: docs/ -``` +### Вставка произвольного контента (Includers) +Информация о вставке произвольного контента (Includers) находится в разделе [Автогенерация и интеграция документации](../guides/includers.md). \ No newline at end of file diff --git a/ru/toc.yaml b/ru/toc.yaml index c06a61f..523ff07 100644 --- a/ru/toc.yaml +++ b/ru/toc.yaml @@ -153,8 +153,17 @@ items: items: - name: Контентная аналитика href: guides/content-analytics.md - - name: Генерация из OpenAPI-спецификации - href: guides/openapi.md + - name: Автогенерация и интеграция документации + href: guides/includers.md + items: + - name: Generic + href: guides/generic.md + - name: Open API + href: guides/openapi.md + - name: Unarchive + href: guides/unarchive.md + - name: Source Docs + href: guides/source-docs.md - name: Вакансии hidden: true items: