Como converter o script de shell bash para o Markdown?

Question

Imagine que um tenha trabalhado em vários scripts de implantação.

Esses scripts de shells são strongmente documentados com comentários e links e devem ser lidos por humanos.

Não seria útil convertê-los para um README.md ou INSTALL.md, por exemplo, para torná-lo mais compatível com o repo?

Por que você pode fazer isso? Bem, para começar, evita-se duplicar o esforço quando houver substancial sobreposição. Também estaria de acordo com o Princípio da Fonte Única da Verdade

    

Answer 1

O uso de documentos aqui em scripts, em oposição ao mais comum # , pode facilitar a transição para outras formas de documentação. Por exemplo:

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

Veja o exemplo do tldp 19-2 em documentos para saber mais.

    

Answer 2

Comentários explicando como partes complicadas de um programa raramente funcionam em um leia-me, seja qual for o formato.

Já existem pacotes em que a saída de chamar um programa com -h é usada como leia-me ou como man page. Por exemplo. GNU help2man faz isso.

IMO, se os scripts de shell se tornam tão complicados que precisam de documentação pesada (seja para explicar o uso ou a operação), você deve considerar reescrevê-los em Python / Perl / Ruby.

    

Answer 3

Parece que você está tentando reinventar o Doxygen . O Doxygen pode criar não apenas o Markdown, mas também HTML, PDF, LaTeX, RTF, man pages e muito mais.

Como enviado, o Doxygen não suporta scripts de shell como entrada, mas há um casal de ways para transformá-lo em coping.

    

Answer 4

Por favor, dê uma olhada no link

Este arquivo de marcação é na verdade um arquivo bash puro. Você pode executar este arquivo usando o bash diretamente.

Alguns trechos de código:

...
### 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]}"
...