Skip to main content

Автовставка истории изменений в техническую документацию на AsciiDoc

Задача

При написании технической документации является хорошим тоном включать секцию с историей изменений (т.н. Revision History). Как правило, сама документация также хранится в гите и имеет свою историю изменений, поэтому грех этим не воспользоваться, чтобы автоматизировать процесс.

Решение

Рассмотрим решение задачи на базе стандарта AsciiDoc, который в последнее время набирает всё большую популярность среди прогрессивно настроенных инженеров и причастных к их результатам деятельности тех.писателей.

Примем, что для истории ревизий нам необходима следующая информация:

  • дата изменения
  • имя автора изменения
  • суть изменения

Для формирования таблицы с историей ревизий используем замечательную команду git log:

— как видим на выходе отличная заготовка для asciidoc-таблицы.

Подробнее об опциях команды:

  • —max-count= — указываем желаемое число последних коммитов
  • —branches= — если интересуют только конкретные ветки (например release/production), указываем тут
  • —tags= — аналогично с тегами, можно задавать паттерн типа rev*.*, v?.?.? и т.п.
  • —no-merges — не выводить в лог слияния веток

У меня установлен гит довольно старый (v1.8), в новых версиях появилась кудо более гибкая кастомизация даты. Тонкую настойку на славянский формат даты «19.2.2015» в новом гите можно осуществить следующей командой:

Также в зависимости от того хранится ли документация отдельно либо является частью репозитария СФ-блока будет различаться git log, возмодно потребуется указывать конкретный исходник документа или группу исходников, например:

или: 

Итоговый скрипт

Получившийся скрипт выглядит следующим образом:

Вызов скрипта: 

В сборочном .adoc-файле включаем сгенерированный файл в соответствующую секцию: 

Также будет полезно добавить revhist.adoc в .gitignore (как файл, генерируемый автоматически); и в мейкфайл — как зависимость при сборке конечного PDF.

 

 

читать...

[opensource]: Мои скрипты для EDA/CAE/CAD

Приведенное ниже — описание к коллекции моих EDA-скриптов для работы с тулами для ASIC и FPGA

Конвертор из UCF в XDC

Конвертирует для ПЛИС Xilinx привязки ножек и стандартов из формата ucf (Xilinx ISE) в новый формат xdc (Xilinx Vivado). Использование:

В текущей директории появится файл FILENAME.xdc.

Пример входного ucf-файла

Пример сгенеренного утилитой xdc-файла

(далее…)

читать...

bash: советы и шпаргалки

Архивация в несколько потоков

Понадобилось по работе делать снапшоты несколько-GB-тных логов и нетлистов прогонов синтеза под ПЛИС, есть несоклько архиваторов использующих многопоточность/многоядерность, попробовал pbzip2, установим:

Сама строка из мейкфайла:

тут делаем tar’ом из нескольких файлов один и передаем в pbzip2, конечный файл называем текущей датой, именем проекта и текущей веткой гита, подробнее про опции pbzip2:

  • 7 — степень компрессии 1..9(лучше,медленне),  по факту — размер блока 7 = 700 КБ
  • force — перезаписать если файл уже существует
  • read — означает зачитать входной файл в ОЗУ и там разбить по процессорам
  • m2000 — сколько оперативки в МБ использовать. 2ГБ — это практический максимум
  • p16 — принудительное задание сколько ядер юзать

(далее…)

читать...

[CLI] Работа с изображениями в линуксе

ImageMagick: однострочники

Узнать размеры изображения

По вертикали:

По горизонтали:

Склейка нескольких картинок в один файл

Склеить все изображения в директории в матрицу 2х2 по 4 изображения:

Склеить 2 изображения в столбец 1х2 (по вертикали):

Склеить 2 изображения в строку 2х1 (по горизонтали):

Подписать каждое изображение в коллаже именем файла:

  • -geometry +10+10 — белые поля вокруг каждого изображения, заданные в пикселях
  • -frame 10 — 3D-рамка, пиксели
  • -label %f — подпись

Рассово-верный резайс картинок

(далее…)

читать...

CentOS 7: советы и шпаргалки

Работа в GUI

Х-сервер

Команда рестарта Х-сервера (для Гнома):

аналогичного эффекта можно добиться перезапуском dbus

Команда убий1ства Х-сервера:

(далее…)

читать...