Создание документации из выходных данных Shell

Это не совсем полный ответ на ваш вопрос, но, надеюсь, это даст вам начало.

bash имеет команду script. Это достаточно запутанное имя, а? По сути, script — это интерактивный регистратор терминала. Поскольку для него нет записи whatis, вот начало страницы man:

$ man script | head -n 17 | sed '/^$/d'
SCRIPT(1)                        User Commands                       SCRIPT(1)
NAME
       script - make typescript of terminal session
SYNOPSIS
       script [options] [file]
DESCRIPTION
       script makes a typescript of everything displayed on your terminal.  It
       is useful for students who need a hardcopy  record  of  an  interactive
       session  as  proof  of  an  assignment,  as  the typescript file can be
       printed out later with lpr(1).
       If the argument file is given, script saves the dialogue in this  file.
       If no filename is given, the dialogue is saved in the file typescript.

Позвольте мне привести вам пример, затем я покажу вам подробности того, что я делаю с этой командой, и дам представление о том, как ее можно использовать для выполнения. Я запускаю это с моего терминала Cygwin.

$ script
Script started, file is typescript

$ pwd
/home/me

$ # This is a comment

$ ping google.com
PING google.com (172.217.12.206): 56 data bytes
64 bytes from 172.217.12.206: icmp_seq=0 ttl=51 time=68 ms
64 bytes from 172.217.12.206: icmp_seq=1 ttl=51 time=67 ms
64 bytes from 172.217.12.206: icmp_seq=2 ttl=51 time=67 ms
64 bytes from 172.217.12.206: icmp_seq=3 ttl=51 time=67 ms
64 bytes from 172.217.12.206: icmp_seq=4 ttl=51 time=68 ms
64 bytes from 172.217.12.206: icmp_seq=5 ttl=51 time=67 ms

----google.com PING Statistics----
6 packets transmitted, 6 packets received, 0.0% packet loss
round-trip (ms)  min/avg/max/med = 67/67/68/67

$ # End of Comment

$ cd /

$ pwd
/

$ exit
exit
Script done, file is typescript

$ pwd
/home/me

Теперь посмотрим на полученный файл. Не пытайтесь использовать head или cat, потому что вы не увидите проблемы (или функции, если хотите `^C'), с которой мы столкнулись.

Вот первые несколько строк из vim typescript

Вы увидите последовательности выхода и управления. Их можно удалить (см. раздел Очистка вывода ниже).

Теперь вы можете настроить фильтр doxygen, подобный описанному здесь

(Вот оно, так как ссылки могут умереть)

Doxygen не поддерживает файлы сценариев bash. Хотя это, вероятно, имеет смысл, чтобы не поддерживать их (определить файл сценария bash с точки зрения функций и переменных), всегда есть несколько в исходном дереве, которые должны быть включены в документ.

Проще всего добавить файлы сценариев, не изменяя их, поэтому используйте входной фильтр doxygen. Входные фильтры довольно хорошо работают с командами sed или awk из командной строки, поэтому здесь мы сделаем простой, который позволит вам добавлять строки команд Doxygen, начинающиеся с ##.

Отредактируйте эти строки в вашем Doxyfile:

FILE_PATTERNS = *.sh *.awk

INPUT_FILTER = "sed -e 's|##|//!|'"

FILTER_SOURCE_FILES = YES

Добавьте краткое описание вверху каждого файла:

## functions for OpenEmbedded, and Jenkins -*- shell-script -*-.

## @author rickfoosusa

## @file

Как правило, все, что имеет # для комментария, будет работать, но для языков вы получите намного больше документации, используя фильтр вроде asm4doxy.pl http://rudy.mif.pg.gda.pl/~bogdro/inne/asm4doxy.txt

Надеюсь, это укажет вам правильное направление. Я надеюсь вернуться и немного конкретизировать его.

Очистить вывод

Я использую следующие два файла, чтобы избавиться от escape-последовательностей, скрипт perl

#!/usr/bin/perl
#
##############################################################################
# Takes escape and control sequences out of the `script` command's output
#
# @file output_scrubbed_script.pl

#
# Okay, I found this all over the internet, it's just my favorite.
# This removes all unwanted junk (control characters, etc) from the output
# of the Linux script command.
# It's imperfect. It struggles with vim, and it doesn't do too well with up
# arrows and tab completion, but I can usually at least see and understand
# what I did.
#
##############################################################################

while (<>) 
{
    s/ \e[ #%()*+\-.\/]. |
       \r | # Remove extra carriage returns also
       (?:\e\[|\x9b) [ -?]* [@-~] | # CSI ... Cmd
       (?:\e\]|\x9d) .*? (?:\e\\|[\a\x9c]) | # OSC ... (ST|BEL)
       (?:\e[P^_]|[\x90\x9e\x9f]) .*? (?:\e\\|\x9c) | # (DCS|PM|APC) ... ST
       \e.|[\x80-\x9f] //xg;
       1 while s/[^\b][\b]//g; #remove all non-backspace followed by backspace
    print;
}

и скрипт bash

#!/bin/bash
#
##############################################################################
# Runs the clean-up
#
# @file script_scrubber.sh
# @author bballdave025
#
# See the usage variable
#
##############################################################################

usage="Usage is:\n > script_scrubber.sh <unscrubbed-file> "\
"[<alternate-filename>]\n"\
"If no <alternate-filename> argument is given, the <unscrubbed-file> \n"\
"will be cleaned in place.\n\n"\
"This script takes the output of the Linux script command and cleans"\
"control characters and other unwanted artifacts."\
"It uses output_scrubbed_text.pl\n"

scrubber_path="$HOME"
scrubber_location="${scrubber_path}/output_scrubbed_text.pl"

if [[ ! -f "${scrubber_location}" ]]; then
  echo -e "Fatal error! ${scrubber_location} does not exist."
  exit 1

fi #endof:  if [[ -f "${location}/output_scrubbed_text.pl" ]]

if [[ ! -x "${scrubber_location}" ]]; then
  chmod +x "${scrubber_location}"
fi #endof:  if [[ ! -x "${scrubber_location}" ]]

if [[ $# -eq 0 ]]; then 
  echo "No argument given."
  echo -e "${usage}" 
  exit 2

elif [[ $# -eq 1 ]]; then
  if [[ $1 == "--help" ]]; then
    echo -e "${usage}"
    exit 0
  else
    "${scrubber_location}" $1 > tmp && mv tmp $1
  fi #endof:  if [[ $1 -eq "--help" ]]

elif [[ $# -eq 2 ]]; then
  "${scrubber_location}" $1 > $2

else
  echo "More than two arguments given."
  echo -e "${usage}"
fi #endof:  if [[ $# -eq <0,1,2,else> ]