4

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

Improve this question

5 Answers 5

Reset to default
2

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.

Improve this answer
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.

Improve this answer
1

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.

Improve this answer
3
  • 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
    Feb 19, 2015 at 10:02
  • 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
    – cavalcade
    Feb 19, 2015 at 10:07
  • @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.
    – Anthon
    Feb 19, 2015 at 13:49
1

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]}"
...
Improve this answer
0

To me, it sounds like you want to generate markdown documentation directly from the source-code of your scripts. This sounds very much like noweb to me, but noweb doesn't (afaik) support markdown as a documemtation format. You could probably add support for it, though.

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .