Подход documentation as code с помощью PlantUML и MKDocs

Документация как код

Работа с PlantUML

Почему PlantUML?

1. Простой синтаксис. PlantUML использует текстовый формат, который легко читать и писать. Это делает его доступным даже для тех, кто не знаком с визуальными инструментами для создания диаграмм.
2. Автоматизация. С помощью PlantUML можно автоматизировать создание диаграмм, интегрируя его в процесс сборки и развёртывания. Это позволяет поддерживать документацию в актуальном состоянии.
3. Интеграция с системами контроля версий. Текстовый формат PlantUML легко интегрируется с системами контроля версий, такими как Git. Это позволяет отслеживать изменения в диаграммах так же, как и изменения в коде.
4. Поддержка различных типов диаграмм. PlantUML поддерживает создание различных типов диаграмм, включая диаграммы классов, последовательностей, состояний, развёртывания и, конечно же, C4-модель.
5. Лёгкость обновления и поддержки. Обновление диаграмм в PlantUML так же просто, как редактирование текста. Это облегчает поддержание актуальности документации по мере развития проекта.

Как применяется PlantUML с C4-моделью?

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

• Это инструмент для создания диаграмм на основе текстового описания. Он поддерживает множество типов диаграмм, включая те, которые используются в C4-модели.
• PlantUML позволяет автоматически генерировать диаграммы, что упрощает их создание и обновление.
• PlantUML можно использовать для реализации диаграмм C4, импортируя соответствующие шаблоны.

Создание диаграмм в PlantUML

• User — класс, представляющий пользователя, с атрибутами name, email и списком членств.
• Membership — класс, представляющий членство, с атрибутами type, startDate, endDate и методами activate(), cancel().
• Schedule — класс, представляющий расписание, с атрибутами date, activity и методами addActivity(), removeActivity().
• Payment — класс, представляющий платежи, с атрибутами double amount, date и методом processPayment().

Импорт шаблонов C4

1. Перейдите на github репозиторий с C4 и скачайте шаблоны PlantUML для C4.
2. Сохраните шаблоны C4 в вашем проекте. Обычно это файлы C4_Context.puml, C4_Container.puml, C4_Component.puml и C4_Code.puml.
3. Импортируйте необходимые шаблоны в ваши файлы PlantUML, добавив строку !include в начало файла.

@startuml
!include C4_Context.puml
!include C4_Container.puml
!include C4_Component.puml
!include C4_Code.puml
@enduml 

Работа с системой контроля версий

• .gitignore: файл для указания файлов и директорий, которые должны быть проигнорированы Git.
• README.md: файл с описанием проекта, содержащий основную информацию и инструкции.
• diagrams/: директория для хранения всех диаграмм C4.
  • context/: поддиректория для диаграмм контекста.
    • FitLife_Context.puml: диаграмма контекста для системы FitLife.
  • container/: поддиректория для диаграмм контейнеров.
    • FitLife_Container.puml: диаграмма контейнера для системы FitLife.
  • component/: поддиректория для диаграмм компонентов.
    • FitLife_Component_WebApp.puml: диаграмма компонентов для веб-приложения FitLife.
  • code/: поддиректория для диаграмм кода.
    • FitLife_Code_Membership.puml: диаграмма кода для компонента управления членством FitLife.
• src/: директория для хранения исходного кода проекта.
  • main/: поддиректория для основного кода приложения.
  • test/: поддиректория для тестов.

FitLife/
├── .gitignore
├── README.md
├── diagrams/
│   ├── context/
│   │   └── FitLife_Context.puml
│   ├── container/
│   │   └── FitLife_Container.puml
│   ├── component/
│   │   └── FitLife_Component_WebApp.puml
│   └── code/
│       └── FitLife_Code_Membership.puml
└── src/
    ├── main/
    │   └── ...
    └── test/
        └── ... 

• Создайте репозиторий Git и добавьте файлы .puml или .plantuml в репозиторий.
• Используйте команды Git для коммита и пуша файлов:

git add diagram.puml
git commit -m "Add initial PlantUML diagram"
git push origin main 

Автоматизация создания диаграмм с помощью PlantUML

name: PlantUML Diagrams

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  generate-diagrams:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v2

    - name: Set up Java
      uses: actions/setup-java@v2
      with:
        java-version: '11'

    - name: Install PlantUML
      run: sudo apt-get install plantuml

    - name: Generate Diagrams
      run: |
        plantuml diagrams/context/*.puml
        plantuml diagrams/container/*.puml
        plantuml diagrams/component/*.puml
        plantuml diagrams/code/*.puml

    - name: Commit Diagrams
      run: |
        git config --local user.email "github-actions[bot]@users.noreply.github.com"
        git config --local user.name "github-actions[bot]"
        git add diagrams/**/*.png
        git commit -m "Automated diagram generation"
        git push origin main
      if: success() 

Что почитать о PlantUML?

Работа с MkDocs

Интеграция PlantUML с MkDocs

pip install mkdocs-plantuml 

pip install mkdocs_puml 

plugins:
    - plantuml:
        puml_url: https://www.plantuml.com/plantuml/ 

```puml
@startuml
title FitLife Context Diagram

top to bottom direction

!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Component.puml

Person(user, "User", "A user of the fitness club system")
Person(admin, "Administrator", "An administrator managing the system")
System(FitLifeSystem, "FitLife System", "System managing memberships, schedules, and payments")

System_Ext(api, "Third-Party API", "External API for fitness data integration", "Uses REST API, JSON data format")
System_Ext(bank, "Bank System", "External bank for processing payments", "Uses SOAP, XML data format")
Rel(user, FitLifeSystem, "Uses the system")
Rel(admin,FitLifeSystem,"Manages the system")
Rel(FitLifeSystem,api,"Fetches fitness data")
Rel(FitLifeSystem,bank,"Processes payments")

@enduml
``` 

mkdocs serve 

• Откройте браузер и перейдите по адресу http://127.0.0.1:8000, чтобы увидеть сгенерированную документацию.
• Для генерации статического сайта выполните команду:

mkdocs build 

Что почитать про MkDocs

Итоги

• Подход «Документация как код» позволяет поддерживать актуальность и согласованность документации с кодом проекта.
• Чтобы эффективно создавать документацию и управлять ею, можно использовать инструменты PlantUML и MkDocs. С их помощью удобно визуализировать архитектуру и автоматизировать процессы.
• Большим преимуществом этих инструментов является возможность интеграции с моделью С4 и системами контроля версий.