☰

如何将 bash shell 脚本转换为 Markdown？

tag-icon • tag-icon bash shell-script conversion markdown
如何将 bash shell 脚本转换为 Markdown？

想象一下，一个人一直在编写一堆部署脚本。

这些 shell 脚本有大量注释和链接记录，旨在供人类阅读。

例如，将它们转换为 README.md 或 INSTALL.md，以使其对存储库更加友好，不是很方便吗？

你为什么可以这样做？首先，可以避免可能存在大量重叠的重复工作。这也将符合单一真相来源原则

答案1

在脚本中使用此处文档而不是更常见的文档#可以顺利过渡到其他形式的文档。例如：

#!/bin/sh
case $1 in (*-h*)
sed '/^:/,/^DOC/!d;s/^:/cat/' "$0" |sh -s "$@"
exit;;esac
: <<DOC
Enter as many lines of documentation as you might need - 
just don't begin any but the first with : or the last with DOC. 
"Quotes are " fine - and $params can be expanded if you 
don't quote the DOC delimiter.
DOC
... #shell script
... #more of same
: <<\DOC
- *Markdown Comment* -
    - or you can quote the delimiter and be more 
     free to use `backquotes` or whatever you like. 
     You can mark the comments up in markdown 
     in the first place, and print them w/ `"$0" -h`.
DOC

看此处文档中的 tldp 示例 19-2了解更多。

答案2

听起来你正试图重新发明强力氧。 doxygen 不仅可以创建 Markdown，还可以创建 HTML、PDF、LaTeX、RTF、手册页等。

交付时，doxygen 不支持 shell 脚本作为输入，但是有一个夫妻的方法用手臂将其扭转成应对状。

答案3

无论格式如何，解释程序复杂部分如何工作的注释很少出现在自述文件中。

已经有一些软件包将调用程序的输出-h用作自述文件或man页面。例如GNU帮助人例如这样做。

IMO，如果您的 shell 脚本变得如此复杂以至于需要大量文档（解释用法或操作），您应该考虑用 Python/Perl/Ruby 重写它们。

答案4

对我来说，听起来您想直接从脚本的源代码生成 Markdown 文档。对我来说，这听起来很像 noweb，但 noweb 不（据我所知）支持 markdown 作为文档格式。不过，您也许可以添加对它的支持。

相关内容