Skip to main content

MKDocs

Використовуємо для генерації документацій по продуктах на напрямках діяльності.

Необхідні знання​

  1. Володіння інструментами
  2. Розуміти загальні вимоги до змісту, неймінгу, стилю, вивчити приклади типових сторінок
  3. Розуміти програму і як вона працює, всі процеси, бути користувачем
  4. Використовувати додаткові блоки, виділення слів, коду, блоки, посилання

Вимоги​

Зміст і типові сторінки​

???+ example "Map50 приклад змісту"

```bash
# Зміст Документації
- Архітектура
    - компоненти
    - стек
    - масштабування
    - open source - та подяки - дописати
- index.md      - Головна
    - скорочена назва
    - повна назва
    - призначення
    - атрибуція - завдяки кому зроблено
    - посилання
    - з чого почати
    - склад системи
    - стандарти
- кабінет       - підсистема 1
- валідатор     - підсистема 2
- база даних    - ERD, опис схем
- changelog     - зміни версій
- /api/         - опис Open API
- нормативна база
- теорія        - якщо треба

# Кабінет - приклад підсистема
- головна
    - скорочена назва
    - повна назва
    - призначення - Автоматизація процесу виробництва, перевірки,
            моніторингу картографічних наборів даних.
            А також є єдиною платформою  комунікації учасників
- реєстри
- бізнес - процес
    - реєстрація та вхід виробників
    - отримання вихідних даних
    - завантаження і перевірка результатів робіт
    - проведення комісії з прийомки
    - моніторинг стану виконання
- структура БД
- теорію - можливості

```

Інструменти​

  • Visual Studio Code - IDE.
  • Gitlab
  • Screenpresso - для знімок екрану - розширений функціонал, в тому числі дозволяє нумерувати елементи на зображенні.
  • Markdown all in one - розширення для VSCode, що дозволяє робити передперегляд файл .md формату.

Приклади документацій​

Структура документації​

index.md                           - (файл, який містить: назву системи, короткий опис, демо (посилання на портал), розділи документації, використані технології, стандарти, корисні посилання)
standard.md                        - стандарти
changelog.md                       - changelog
├── Адмін частина                  - опис адміністративної частини та автоматизованих робочих місць
│   ├── АРМ1
│   ├── Таблиця1
├── Публічна частина
│   ├── головна
│   ├── геопортал
├── Кабінет                        - кабінет користувача на порталі
│   ├── реєстрація
│   ├── опис можливостей
├── База даних                    -  Описується структура бази даних, всіх таблиць робочих схем (реєстри і т.д.)
├── API                           -  Інтеграція
├── Адміністрування               -  Користувачі, доступи

Треба дати приклад

Build документації​

  • Автоматично /doc gitlab.ci
  • Для генерації нової версії документації запустіть команди git pull && mkdocs build на сервері в папці документації, яку змінюєте.

Опис робочого процесу​

  1. При першому редагуванні файлів - клонувати локально проєкт documentation:

    git clone -b dev https://git.softpro.ua/softpro/documentation.git

  2. Відкрити проєкт через VS Code або іншу IDE, створити/відкрити файл який потрібно сформувати.

  3. Редагувати файл за допомогою синтаксису Markdown.

  4. Таблиці рекомендуємо створювати через сервіс Mardown Tables.

  5. Зберегти зміни локально та запушити їх на Git.

  6. Вставка зображень ctrl+alt+v

  7. Після цього потрібно перегенерувати збірку документації. Для цього потрібно зайти на 160 сервер в сховище /data/softpro/cdn/documentation/{folder_name}, де folder_name - папка першого рівня проєкту, розділ (наприклад, dev чи pm).

    Після переходу в сховище запустити команду git pull && mkdocs build.

Markdown extension​

  1. Admonitions https://squidfunk.github.io/mkdocs-material/reference/admonitions/#removing-the-title ??? Приклад 1

    Accordion

    ???+ Приклад 2

    Accordion

!!! Example

Приклад
  1. Tab https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs

=== "C"

``` c
#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}
```

=== "C++"

``` c++
#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}
```

Plugin

  1. Search
  2. Mkpdfs Export https://comwes.github.io/mkpdfs-mkdocs-plugin/pdf/documentation.pdf
  3. pdf Export https://github.com/zhaoterryy/mkdocs-pdf-export-plugin
  4. mkdocs-with-pd https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs-material/README.md?ref=morioh.com&utm_source=morioh.com

Генерація PDF - приклад документу

https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs-material/document.pdf