How to convert bash shell script to Markdown?

Question

Imagine one has been working on a bunch of deploy scripts.

These shells scripts are heavily documented with comments and links and are meant to be read by humans.

Wouldn't it be handy to convert that those to a README.md or INSTALL.md, for example, to make it more repo friendly?

Why might you do this? Well for starters there is avoiding duplicating effort where there can be substantial overlap. Also it would be in keeping with the Single Source of Truth principle

Solution 1

Using here-documents in scripts as opposed to the more common # can make for smooth transition to other forms of documentation. For example:

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

See tldp's example 19-2 on heredocuments for more.

Solution 2

It sounds like you're trying to reinvent doxygen. doxygen can create not only Markdown but also HTML, PDF, LaTeX, RTF, man pages, and more.

As shipped, doxygen doesn't support shell scripts as input, but there are a couple of ways to arm-twist it into coping.

Solution 3

Comments explaining how a complicated parts of a program works seldom have no place in a readme, whatever format.

There already are packages where the output of calling a program with -h is used as readme or as man page. E.g. GNU help2man e.g. does this.

IMO, if you shell scripts become so complicated that they need heavy documentation (either to explain the usage, or the operation), you should consider rewriting them in Python/Perl/Ruby.

Solution 4

Please take a look at https://github.com/nerds-odd-e/bbuddy/blob/master/DEPLOY.md

This markdown file actually is a pure bash file. You can run this file using bash directly.

Some code snippets:

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

View more solutions

Comments

[cavalcade]

I get what you saying, and it would not be appropriate in the use case you mentioned. However, I do think it can be useful in certain scenarios, like devops and CI/CD. BTW these are not complicated scripts. But certain choices should be explained to the new user. Onboarding a new web developer for example to the dev env. You could create a Readme explaining all the steps (as many do). Another approach might be to do what I've described as a hybrid (combine a well docced setup script with an auto-gen readme). One would not need to worry about keeping scripts and docs in sync.

[cavalcade]

For example, coderwall.com/p/hwkjba/… Now, it's not a perfect automated script, but it's close to working, and hopefully illustrates the original question better

[Anthon]

@MattTag Documentation always has a target group. I would not be the target group for that example, as I hate to have time wasted by things like "Unpack the tar zipped file" when the next line does (and tells me, because of my experience) exactly the same. In my experience the only remedy is hiding details in properly named abstractions (function etc.) thereby minimizing the need for comment interjections.