Comments / Profile of fiddle-de-dee / Habr

Поташников Николай Михайлович @fiddle-de-dee

Системный аналитик

Profile Publications 12Comments 83Bookmarks 8

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

fiddle-de-dee Oct 12 2021 at 20:03

В комментариях довольно сложно показать.

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

Для этого у нас есть вот такой bash-скрипт.

echo "My note" >mynote.txt
grep MemTotal /proc/meminfo >> mynote.txt
df -t ext4 --output=size >> mynote.txt
df -t ext4 --output=avail -B G | grep "[0-9]\+G$" | sed 's/ //g' \
  | sed -e 's/\([0-9]\+G\)/!$available_hdd = "\1b"/g' > flex-params.pu

Он дает на выходе файл mynote.txt

My note
MemTotal:       10816304 kB
1K-blocks
 65274444

И файл flex-params.pu

!$available_hdd = "16G"

Документ наверху -- это Open Document (LibreOffice), но на самом деле -- это схемка в формате plantuml, обёрнутая Asciidoc'ом (architect-vision.adoc)

= My note configuration

== HDD and Memory

[plantuml, png, fitrect="210x260mm", srcdpi="300", width="40%"]
.My notebook configuration
....
skinparam dpi 300
include::flex-params.pu[]
package "My note" {
    component hdd [
      HDD
      ----
      Total: 64Gb
      Available: $available_hdd
    ]
    component memory [
      Memory
      ----
      10Gb
    ]
memory -- hdd
....

Как видим, свободная память сразу засасывается в картинку.

Тестируем всё это, например, через TestDoc.groovy.

@Grapes([
    @Grab(group='com.approvaltests', module='approvaltests', version='12.1.1')
])
import org.junit.jupiter.api.Test
import org.approvaltests.Approvals
import java.nio.charset.StandardCharsets
import java.nio.file.Files
import java.nio.file.Path
class MyNote {
    @Test
    void testMyNote() {
        String content = Files.readString(Path.of("mynote.txt"), StandardCharsets.UTF_8);
        Approvals.verify(content);
    }
}

Запускаем, например, так:

docker run --rm -u root -v "$PWD":/home/groovy/scripts -w /home/groovy/scripts groovy groovy TestDoc.groovy

Если скрипт выдает ошибку, то у нас возникает файл MyNote.testMyNote.received.txt. Сравниваем его мёрджером с MyNote.testMyNote.approved.txt, который содержит предыдущее состояние mynote.txt. IDE при запуске теста сразу запускает мёрджер, что удобно.

Из рисунка ясно, что памяти стало больше. Корректируем документацию (если нужно -- может, мы округляем память до 10 Гб), мёрджим всё в одобренную версию (approved). Далее собираем документацию, например, так.

docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od a-od architect-vision.adoc odt

И получаем такой же файл, как наверху, только актуальный. MyNote.testMyNote.approved.txt и mynote.txt находятся в системе контроля версий, случайно проигнорировать не получится, только намеренно. Но тут есть другие подходы.