Search... (alt + k)

Zendoc-инструкция

status

in progress

Zendoc — это данные, аннотированные так, чтобы они выглядели как структурированный динамический текст, который может использовать другие данные.

Каждый документ — это данные. Назовем это ресурсом. Ресурс — это упорядоченный набор ключей и значений (map в терминах clojure).

Ключи верхнего уровня начинаются с новой строки с :, потом указывается их значение в EDN через пробел, например :this-is-a-key "value".

Ресурс хранится в базе данных и может быть доступен по имени или с помощью фильтра.

Каждый документ получает свое имя от пути в файловой системе, начиная от корня проекта. Это имя в качестве символа может использоваться для ссылки на документ/ресурс. Например путь mywiki/people/niquola.zd будет переведен в имя mywiki.people.niquola.

Каждый документ в zendoc состоит из последовательности ключей (keypaths), значений и аннотаций.Ключ может иметь аннотацию (метаданные), например ^badge. Благодаря аннотации данные отображаются в определенном виде.

Для многострочности используется специальная нотация, которая начинается с :key md/ и заканчивается новой строкой с ключом или аннотацией.

Николай Рыжиков представляет zendoc: видео 15 мин.

Все пожелания по улучшению Zendoc и наполнению контентом этой страницы можно оставлять тут — 132.

  • :menu-order - порядок сортировки документа в панели навигации
  • :icon - иконка страницы
  • :title - заголовок страницы и пункт меню
  • :summary -
  • :tag - и название тэга - выводит список всех схем с указанным тэгом.
  • :toc

К главному заголовку можно добавить иконку.

Иконки можно выбрать здесь.

  :icon [:fa :fa-graduation-cap]

Оглавление можно добавить через :toc.

Картинку можно положить в репозиторий или сослаться по ссылке.

Чтобы картинка отрисовалась, можно использовать анатацию ^img.

  ^img
  :image "https://www.hl7.org/fhir/conformance.jpg"

  ^img
  :image "local.webp"


  :image-in-text md/

      Можно вставить картинку в текст [[img local.webp]] или ![](local.webp)

Результат:

Можно вставить картинку в текст или .

Аннотация — это подсказка, которая позволяет интепретатору понять, как рисовать содержимое ключа, например ^badge.

Аннотация подвязывается к ключу:

    ^badge
    :any-key "value"

Список аннотаций:

  • ^collapse — свернуть данные под заголовок
  • ^badge — прикрепляется как лейбел вверху страницы
  • ^title — отрисовать заданный заголовок
  • ^link-badge — маленький бейджик, внутри которого будет ссылка; то же, что и badge
  • ^href / link — способ отрисовать ссылки
  • ^img — вставить картинку
  • ^table — отрисовка таблицы
  • ^hide — не отрисует данные
  • ^yaml — отрисовать yaml-код с подсветкой
  • ^edn — отрисовать edn-код с подсветкой
  • ^video — вставить видео
  • ^zen/schema — способ отрисовать zen schema в виде дерева, например для вывода профиля на странице документации
  • ^disc — ссылка на дискуссию в GitHub
  • ^hiccup
  • ^attribute
  ^attribute
  :part-of core.Organization

  • Выделить код: `code()`code()
  • Либо выделить код: [[code code()]]code()
  • Выделить жирным: **bold**bold
  • Выделить курсивом: __italic__italic

  • Можно сослаться на человека: @niquolaНиколай Рыжиков
  • Можно сослаться на документ: #readmeFHIR RU
  • Можно вставить внешнюю или внутреннюю ссылку: [text](link)text
  • Сослаться на поле в ресурсе (здесь ресурс - это zendoc-страница): ((resource people.niquola :telegram)) — niquola
  • Внутри таблиц нужно взять в двойные кавычки: "((resource people.niquola :telegram))"
  • Внутренние ссылки: [соглашения](support.conventions) - соглашения
  • Внутренние ссылки на разделы страниц документации: [Соглашения/Идентификаторы Coding Systems](support.conventions#:code-systems-naming) - Соглашения/Идентификаторы Coding Systems

    ^title "Текст"
    :zentext md/

    подзаголовок (вложенный заголовок) можно задать с помощью вложенных ключей:

    ^title "Списки"
    :zentext:lists md/

Списки начинаютя с *. Вложенные списки с префиксом ...

* list 1 multi line
* list 2
..* sub item 1
..* sub item 2
* list 3

Результат:

  • list 1 multi line
  • list 2
    • sub item 1
    • sub item 2
  • list 3

Пронумерованные списки начинаются с 1). Вложенные с ...

1) item 1
2) item 2
..1) sub item
..1) another
3) item 3

Результат:

  1. item 1
  2. item 2
    1. sub item
    2. another
  3. item 3

Таблицу можно встроить с помощью блока ```table:

  ```table
  name    | email       | phone
  niquola | niq.com     | +7897989 
  mary    | mary.com | +7897555 
  ```

Результат:

name email phone github
niquola niq.com +7897989 [niquola](https://github.com/niquola)
mary mary.com +7897555 [MariaAnf](https://github.com/MariaAnf)

Еще таблицу можно записать с помощью — ^table{:key[{:column1 "value1" :column2 "value2"}]

  ^table
  :table-contacts
  [{:name "niquola":email "niq.com":phone "+7897989" :link "[niquola](https://github.com/niquola)"} 
  {:name "mary":email "mary.com":phone "+7897555" :link "[MariaAnf](https://github.com/MariaAnf)"}]

Результат:

NameEmailPhoneLink

niquola

niq.com

+7897989

mary

mary.com

+7897555

  ^title "Реестр систем кодирования"
  ^table
  :tables:code:code-systems-register
  [
{:Система artifacts.codesystems.cs-rosminzdrav-gender :URI "((resource artifacts.codesystems.cs-rosminzdrav-gender :system))" :OID "1.2.643.5.1.13.13.11.1040" :Описание "НСИ Минздрава Пол пациента"}
{:Система artifacts.codesystems.cs-ffoms-gender :URI "((resource artifacts.codesystems.cs-ffoms-gender :system))" :OID "" :Описание "НСИ ФОМС Пол пациента. Классификатор пола застрахованного (Pol)"}
{:Система artifacts.codesystems.cs-nsi-identity-document :URI "((resource artifacts.codesystems.cs-nsi-identity-document :system))" :OID "1.2.643.5.1.13.13.99.2.48" :Описание "НСИ Минздрава Документы, удостоверяющие личность"}     
{:Система artifacts.codesystems.cs-nsi-diagnosis-justification-degree :URI "http://fhir.ru/core/cs/core-cs-nsi-diagnosis-justification-degree" :OID "1.2.643.5.1.13.13.99.2.795" :Описание "НСИ Минздрава Справочник Степень обоснованности диагноза"}     
{:Система artifacts.codesystems.cs-nsi-diagnosis-nosology-kind :URI "http://fhir.ru/core/cs/core-cs-nsi-diagnosis-nosology-kind" :OID "1.2.643.5.1.13.13.11.1077" :Описание "НСИ Минздрава Справочник Виды нозологических единиц диагноза"}     
]

Результат:

СистемаUriOidОписание
artifacts.codesystems.cs-rosminzdrav-gender

Could not find artifacts.codesystems.cs-rosminzdrav-gender

1.2.643.5.1.13.13.11.1040

НСИ Минздрава Пол пациента

artifacts.codesystems.cs-ffoms-gender

Could not find artifacts.codesystems.cs-ffoms-gender

НСИ ФОМС Пол пациента. Классификатор пола застрахованного (Pol)

artifacts.codesystems.cs-nsi-identity-document

Could not find artifacts.codesystems.cs-nsi-identity-document

1.2.643.5.1.13.13.99.2.48

НСИ Минздрава Документы, удостоверяющие личность

artifacts.codesystems.cs-nsi-diagnosis-justification-degree

http://fhir.ru/core/cs/core-cs-nsi-diagnosis-justification-degree

1.2.643.5.1.13.13.99.2.795

НСИ Минздрава Справочник Степень обоснованности диагноза

artifacts.codesystems.cs-nsi-diagnosis-nosology-kind

http://fhir.ru/core/cs/core-cs-nsi-diagnosis-nosology-kind

1.2.643.5.1.13.13.11.1077

НСИ Минздрава Справочник Виды нозологических единиц диагноза

Способ вывести какие-то сущности:

Пример

  ^table-of {:namespace "people." :columns [:zd/name :group :organization :github]}
  :people

Результат:

Можно вывести значения из файла .yaml в виде таблицы. Может пригодиться, например, для вывода содержимого набора значений.

  ^table
  ^title "Value Set - Таблица из файла .yaml"
  :tables:from-yaml (load "../core/samples/address-use.yaml" :yaml)

Пример содержимого файла .yaml:

- code: home
  display: Адрес постоянной регистрации
  desc: A communication address at a home.
- code: work
  display: Рабочий
  desc: An office address. First choice for business related contacts during business hours.
- code: temp
  display: Адрес фактического проживания
  desc: A temporary address. The period can provide more detailed information.
- code: old
  display: Устаревший
  desc: This address is no longer in use (or was never correct but retained for records).
- code: billing
  display: Почтовый
  desc: An address to be used to send bills, invoices, receipts etc.

Результат:

Missed render-block for :error

{:message "/root/gitopa/workdir/fhir-ru-mirror/docs/support/zen-development/../core/samples/address-use.yaml (No such file or directory)"}

Можно вывести значения из файла .csv в виде таблицы. Может пригодиться, например, для вывода содержимого набора значений.

  ^table
  ^title "Value Set - Таблица из файла .csv"
  :tables:from-yaml (load "../terminology/1.2.643.5.1.13.13.99.2.285_1.2.csv" :csv)

Результат:

Missed render-block for :error

{:message "/root/gitopa/workdir/fhir-ru-mirror/docs/support/zen-development/../terminology/1.2.643.5.1.13.13.99.2.285_1.2.csv (No such file or directory)"}

Блок с кодом можно записать как ```code

Список языков — здесь

  ```code json
   {"a" : 1}
  ```

Результат:

{"a" : 1}

Вкладки можно вставить с помощью блоков с аннотациями, где tabs — контейнер, tab-title — название вкладки, tab-content — ее содержимое, путь задает саму вкладку, он обязательно должен быть внутри контейнера.

Пример:

    ^tabs
    :tabs-example
    ^tab-title
    ~:json:title "JSON"
    ^tab-content
    ~:json:content md/

    **Hello**

    ```code json
        {"key": "value"}
    ```

    ^tab-title
    ~:yaml:title "YAML"
    ^tab-content
    ~:yaml:content "not written yet"

Hello

    {"key": "value"}

not written yet

  ^yaml
  ^title "Пример"
  :samples:one  (load "../core/samples/org-1.yaml" :yaml)

Код можно свернуть:

  ^yaml
  ^collapse
  ^title "Пример 2"
  :samples:one (load "../core/samples/org-1.yaml" :yaml)
Missed render-block for :error

{message: /root/gitopa/workdir/fhir-ru-mirror/docs/support/zen-development/../core/samples/org-1.yaml (No such file or directory)}
Missed render-block for :error

{message: /root/gitopa/workdir/fhir-ru-mirror/docs/support/zen-development/../core/samples/org-1.yaml (No such file or directory)}

Можно добавить ссылку на дискуссию либо к заголовку, либо в теле текста 45

  ^disc 45
  :discussion md/

  Можно добавить ссылку на дискуссию либо к заголовку либо в теле текста [[d 45]]

  :markdown markdown/

  Вы можете использовать [markdown](markdown) — но лучше zentext

  * item-1
  * item-2

Вы можете использовать markdown:key markdown/

  • item-1
  • item-2

  :mindmap:sample mindmap/

  zendoc
  * semantic web
    * resources
    * attributes
    * machine readable
  * knowlege base
    * database
    * links
    * back links
  * zen-lang
    * schema
  * clojure
    * EDN
      * symbols for links
    * hiccup
      * ad-hock markup
    * extension

Для отображения в виде диаграммы нужно использовать нотацию :any-key mm/ flowchart

    :diagram mm/
    flowchart TB
    zendoc-->document
    zendoc-->resource
    resource-->db
    document-->db
    db[(Database)]

flowchart zendoc-->document zendoc-->resource resource-->db document-->db db[(Database)]

Referenced By - список страниц, ссылающихся на открытую страницу. Сейчас это только именованные ссылки - бейджики. Потом добавится поддержка ссылок на страницу с других страниц документации.

Можно описать страницы документации с помощью схемы и добавить какие-то требования, например что у человека на его странице обязательно должны присутствовать какие-то элементы, например указан емейл.

Для этого надо создать файл .edn в папке docs, создать схему.

{ns zendoc

 person
 {:zen/desc "Person"
  :zen/tags #{zen/schema zen/tag}
  :type zen/map
  :confirms #{doc}
  :require #{:name :telegram}
  :keys {:name     {:type zen/string}
         :telegram {:type zen/string :zd/annotations {:block :badge}}
         :github   {:type zen/string :zd/annotations {:block :badge}}
         :email    {:type zen/string :zd/annotations {:block :badge}}
         :phone    {:type zen/string :zd/annotations {:block :badge}}
         :twitter  {:type zen/string :zd/annotations {:block :badge}}
         :person/avatar   {:type zen/string}}}}

На соответствующей родительской странице документации добавить строчку:

  ^hide
  :zd/child-tags #{zendoc/person}

Все вложенные страницы будут валидироваться указанной схемой.

В навигации можно показать число ошибок на странице, например наличие битых ссылок.

Получение значения из схемы

((ztx-get :symbols fhir.ru.core.coverage/CoreCoverage :zen.fhir/profileUri))

Наверх