documentation - JavaDoc 之类的 shell 脚本框架？

Question

是否有可以记录类似于 JavaDoc 生成的 shell 脚本的开源或公共领域框架？我不需要将其仅限于特定风格的 shell 脚本，理想情况下，我想要一个用于在网页上记录 API 或命令行类型命令的通用框架，该框架易于扩展，甚至更好的是自我记录。

Answer 1

如果你有 Perl，这里有一个使用 Perl 的 POD 系统来记录 shell 脚本的例子。

诀窍是将 Perl POD 部分放在 bash “Here-Document”中，紧跟在 null 命令 (no-op) 之后:。

• 从...开始: <<=cut
• 编写 POD 格式的手册页
• 而已。你的 POD 以 结尾=cut，它也被定义为 shell Here-doc 的结尾

然后可以使用所有常用的 Perl 工具（如 perldoc 或 perl2html）处理您的脚本，您甚至可以使用 pod2man 生成真正的手册页。

例如，这里是podtest.sh脚本：

#!/bin/dash

echo This is a plain shell script
echo Followed by POD documentation

: <<=cut
=pod
=head1 NAME

   podtest.sh - Example shell script with embedded POD documentation

...

No rights Reserved

=cut

将此 podtest.sh 添加到您的手册页：

 pod2man podtest.sh >/usr/local/share/man/man1/podtest.sh.1

Answer 2

虽然 Doxygen 不支持 bash 脚本文件，但你可以 让 Doxygen 与 bash 一起工作

如果您不介意文档与代码分开，您绝对应该查看ronn。

您可能还会发现Shocco很有用，尽管它与 JavaDoc 不同（代码是文档的组成部分）。

Answer 3

您可能会考虑Doxygen。虽然它主要用于记录像 JavaDoc 这样的 C-ish 语言，但您可能会想出一个适用于 shell 脚本的设置，但需要一些争论。

Answer 4

文档化的 shell 脚本的标准方法是使用 troff 并在类似于 C 的脚本注释中使用。虽然我建议使用 Steve 帖子中的“Here-Document”方法，如果你真的需要更可扩展的东西来嵌入你的 troff/ pod/rdoc/jdoc 代码。