From ab77889e998c6859c6dc193301d20b87dd79174c Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Wed, 10 Aug 2022 14:50:22 +0300
Subject: [PATCH] =?utf8?q?=D0=94=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82?=
 =?utf8?q?=D0=B0=D1=86=D0=B8=D1=8F=20=D1=80=D1=8F=D0=B4=D0=BE=D0=BC=20?=
 =?utf8?q?=D1=81=20=D0=BA=D0=BE=D0=B4=D0=BE=D0=BC=20=D1=83=20=D0=90=D0=BB?=
 =?utf8?q?=D1=8C=D1=84=D0=B0-=D0=91=D0=B0=D0=BD=D0=BA=D0=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

https://habr.com/ru/company/alfa/blog/680556/
http://www.stargrave.org/InfoRules.html
В ivi мы начали вести документацию, которая в том числе
шла наружу для сторонних разработчиков, в reStructured Text формате, ибо
всё же код на Python был изначально полностью. Каждое изменение API
попадало в отдельный файлик с изменениями в новой версии. Во время
релиза (вроде) запускался скрипт который этот файлик переименовывал в
чётко заданную версию. Во время ревью надо было проверять что все
изменения отражены в документации. И она отдельно собиралась Jenkins
задачей.

У меня было предложение использовать git-notes для хранения кусочков
текста которые должны пойти в changelog, но, действительно, это
требовало большой аккуратности и толком то ничего не упрощало, кроме
того факта, что в репозитории, во время разработки между релизами, не
правился один и тот же changelog файл.

В da160c3c7b3f5393aa37f2d042f9b281264273de писал про мой выбор форматов
документации. Сейчас я reST не использую совсем. Из личных проектов
только PyDERASN с ним остался. Для всего применяю Texinfo с Info и HTML
генерированием. С docstringer.pl скриптом (de290eaa23dc9d16296162f0ff52ed00f506e786):
http://www.git.stargrave.org/?p=dotfiles.git;a=blob;f=bin/bin/docstringer.pl
я собираю документацию из файлов исходного кода. Безусловно только redo
используется, типа:

    doc/docstringer.log.do:
        redo-ifchange *.texi docstringer.pl ../src/*.h
        sed -n 's/^@verbatiminclude \(.*.plantuml.txt\)$/\1/p' *.texi |
            xargs redo-ifchange
        mkdir -p build
        ./docstringer.pl -v ../src . build

    doc/xxx.info.do:
        redo-ifchange ../conf/cmd/makeinfo ../conf/version docstringer.log
        read MAKEINFO < ../conf/cmd/makeinfo
        read VERSION < ../conf/version
        cp -f *.txt build/
        cd build
        MAKEINFO_OPTS="$MAKEINFO_OPTS --set-customization-variable SECTION_NAME_IN_TITLE=1"
        [...]
        $MAKEINFO -D "VERSION $VERSION" $MAKEINFO_OPTS -o ../$3 index.texi

    doc/default.plantuml.txt.do:
        src=${1%.txt}
        redo-ifchange $src ../conf/cmd/plantuml
        read PLANTUML < ../conf/cmd/plantuml
        $PLANTUML -tutxt -pipe < $src

    doc/xxx.html.do:
        rm -rf $1
        MAKEINFO_OPTS="$MAKEINFO_OPTS --html"
        [...]
        MAKEINFO_OPTS="$MAKEINFO_OPTS" . xxx.info.do

Почти везде применяется хотя бы для одной-двух диаграмм PlantUML
(https://plantuml.com/). Недавно смотрел на его документацию и поразился
обилием вещей который он может рисовать. Но я почти только для sequence
диаграмм его использую. Искал более легковесные (не Java) альтернативы,
но уже много лет держу Java только и только ради одной этой программы,
ибо хороша.
-- 
2.48.1