从Shell输出生成文档 [英] Generate documentation from Shell output

问题描述

有没有一种方法/工具可以直接从Shell输出甚至是保存的日志中生成HTML文档（类似于doxygen所做的事情）？如果没有可用的工具，你们是否对如何使用现有工具有任何创意？

Is there a way/tool to generate HTML documentation (similar to what doxygen does) directly from my Shell output or even a saved log ? If nothing is available, do you guys have any creative ideas on how to do that with the existing tools ?

我在想，在打字时，我可以输入一些标记或特殊字符，然后用工具将其作为注释的开头，而键入的其余部分为CLI和输出。

I'm thinking that while typing, I can put some sort of mark or special character and then have a tool pick that up as the beginning of a comment, while the rest of what is typed are CLI and output.

示例：

ubuntu@nso-172-73:~$ # This is a comment
ubuntu@nso-172-73:~$ ping google.com
PING google.com (172.217.9.174) 56(84) bytes of data.
^C
--- google.com ping statistics ---
2 packets transmitted, 0 received, 100% packet loss, time 1008ms

ubuntu@nso-172-73:~$ # End of Comment

推荐答案

这并不能完全回答您的问题，但希望可以为您提供一个开始。

This doesn't quite give a complete answer to your question, but it will hopefully give you a start.

bash 具有脚本命令。这真是一个令人困惑的名字，是吗？基本上， script 是一个交互式终端记录器。由于没有 whatis 条目，因此这是 man 页的开始：

bash has a script command. That's a confusing enough name, eh? Basically, script is an interactive terminal logger. Since there's no whatis entry for it, here's the start of the man page:

$ 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终端上运行它。

Let me give you an example, then I'll show you details of what I do with this command and give an idea of how this could be used to accompl. I'm running this from my Cygwin terminal.

$ 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 ，因为您不会看到问题（或功能，如果您想要

Now we'll look at the resultant file. Don't try head or cat, because you won't see the problem (or feature, if you want the `^C') we encounter.

以下是 vim打字稿

您将看到转义和控制序列。可以将其删除（请参见下面的清理输出部分。）

You'll see the escape and control sequences. Those can be removed (see the Clean Up Output section below.)

现在，您可以设置 doxygen 过滤器，有点像此处

Now, you can set up a doxygen filter, somewhat like the one described here

（在这里，因为链接可能会死）

(Here it is, since links can die)

Doxygen不支持bash脚本文件。虽然这可能使
有意义，但不支持它们（根据
函数和变量来定义bash脚本文件），但是在
源代码树中总应该放置一些内容

Doxygen doesn't support bash script files. While that probably makes sense, to not support them (define a bash script file in terms of functions and variables), there are always a few laying around in a source tree that should go into the document.

添加脚本文件而不更改它们是最简单的，因此使用
doxygen输入过滤器。输入过滤器可与
sed或awk命令行一起很好地工作，因此我们在这里做一个简单的操作，使您可以添加以##开头的
Doxygen命令。

It's easiest to add the script files without changing them, so a doxygen input filter. Input filters work pretty good with command line sed or awk commands, so we'll do a simple one here that lets you add Doxygen commands comeent lines starting with ##.

在Doxyfile中编辑以下行：

Edit these lines in your Doxyfile:

FILE_PATTERNS = * .sh *。 awk

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

FILTER_SOURCE_FILES = YES

在每个文件的顶部添加简短说明：

Add a brief description to the top of each file:

##用于OpenEmbedded的函数，以及Jenkins-*-shell-script-*-。

## @author rickfoosusa

## @file

通常带有＃可以发表评论，但是对于语言
，您可以使用asm4doxy.pl
http://rudy.mif.pg.gda.pl/~bogdro/inne/asm4doxy.txt

Generally anything with # for a comment will work, but for languages you get a lot more documentation by using a filter like asm4doxy.pl http://rudy.mif.pg.gda.pl/~bogdro/inne/asm4doxy.txt

希望这会为您指明正确的方向。我希望能重新整理一下。

Hopefully, this points you in the right direction. I hope to get back and flesh it out a bit.

我使用以下两个文件以摆脱转义序列，使用 perl 脚本

I use the following two files to get rid of the escape sequences, a perl script

#!/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> ]

这篇关于从Shell输出生成文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！