web-dev-qa-db-ja.com

bashシェルスクリプトをMarkdownに変換する方法は？

たくさんのデプロイスクリプトに取り組んでいると想像してみてください。

これらのシェルスクリプトは、コメントとリンクで詳細に文書化されており、人間が読むことを目的としています。

たとえば、それらをREADME.mdまたはINSTALL.mdに変換して、リポジトリをより使いやすくするのは便利ではないでしょうか。

なぜあなたはこれをするのですか？初心者にとっては、実質的な重複が発生する可能性のある重複作業を回避することができます。また、それは 信頼できる唯一の情報源の原則 と一致します。

bashshell-scriptconversionmarkdown
4
cavalcade

あなたは再発明しようとしているようです doxygen 。 doxygenは、Markdownだけでなく、HTML、PDF、LaTeX、RTF、manページなども作成できます。

出荷時、doxygenは入力としてシェルスクリプトをサポートしていませんが、対処するために カップル の ウェイ があります。

2
Warren Young

より一般的な#とは対照的に、スクリプトでヒアドキュメントを使用すると、他の形式のドキュメントにスムーズに移行できます。例えば：

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

詳細については、 heredocumentsのtldpの例19-2 を参照してください。

2
mikeserv

プログラムの複雑な部分がどのように機能するかを説明するコメントは、どのような形式であっても、readmeに配置されることはめったにありません。

-hを使用してプログラムを呼び出す出力がreadmeまたはmanページとして使用されるパッケージはすでに存在します。例えば。 GNU help2man たとえばこれを行います。

IMO、シェルスクリプトが非常に複雑になり、（使用法や操作を説明するために）大量のドキュメントが必要になった場合は、Python/Perl/Rubyでスクリプトを書き直すことを検討する必要があります。

1
Anthon

ご覧ください https://github.com/nerds-odd-e/bbuddy/blob/master/DEPLOY.md

このマークダウンファイルは、実際には純粋なbashファイルです。このファイルは、bashを直接使用して実行できます。

いくつかのコードスニペット：

...
### Install git, curl, unzip
    apt_install git curl unzip

### Download JDK8
    get_url "${MIRROR_SITE}/jdk-${JDK_VERSION}-linux-i586.tar.gz"

### Set `$Java_HOME`
    export Java_HOME="$INSTALL_DIR/${JDK_VERSION_MAP[$JDK_VERSION]}"
...
1
Feng

私には、スクリプトのソースコードから直接マークダウンドキュメントを生成したいようです。これは私にはnowebのように聞こえますが、nowebはドキュメント形式としてマークダウンをサポートしていません（afaik）。ただし、おそらくそれに対するサポートを追加することができます。

0
user328476