In my some 15+ years of software development, I’ve never quite come across the perfect integration between documentation, source code and tests. With the not-so-recent move to Git and Mercurial, dev projects have adopted the MD format for readme’s. The MD format is a text-based markDOWN format that uses special, predetermined characters to place additional, formatting based, rendering suggestions to the markdown viewer. While able to coexist in the code base, markdown still doesn’t offer a fully-fledged integration with the terminal – which is where most development takes place. Thus is born runnable.sh.

The runnable project is a simple bash parser for .MD files. Essentially a bash script, it runs through the MD file, and extracts file options, which can then be selected and executed from the command/terminal prompt.

With simple convention rules on MD files, we can then present and MD file as such:

Runnable

Runnable – scans README.md files for runnable commands”

Runnable aims to remove the barrier between code and documentation. Through the use of formatting conventions and bash scripting, it scans documentation for commands, which can then be run.

01. $ ./runnable.sh

Lists the runnable commands in . “

02. $ ./runnable.sh .

Lists the runnable commands in tests

03. $ ./runnable.sh tests

Generates the test script file containing all commands for the purpose of testing documentation

04. $ ./runnable.sh tests 00

Runs the script file above.

05. $ ./runnable.sh tests     00  -r

# Runnable

Runnable - scans README.md files for runnable commands"

Runnable aims to remove the barrier between code and documentation. Through the use of formatting conventions and bash scripting, it scans documentation for commands, which can then be run. 


```shell
01. $ ./runnable.sh
```

Lists the runnable commands in . "
```shell
02. $ ./runnable.sh .
```

Lists the runnable commands in tests 
```shell
03. $ ./runnable.sh tests
```

Generates the test script file containing all commands for the purpose of testing documentation
```shell
04. $ ./runnable.sh tests 00
``` 

Runs the script file above.
```shell
05. $ ./runnable.sh tests     00  -r 
```

As can be seen in the example, the formatting differences aren’t significant. The MD file in this example prefixes executable commands with ‘. $ ‘. This then allows you to number, or label, commands.

As for the actual script, it’s trivial.


if [ -z "$1" ]; then
  echo "Runnable - scans README.md files for runnable commands"
  echo "Tag 1.0.0"
  echo "Get the latest from https://github.com/munafsheikh/runnable"
  echo "Usage: ./runnable.sh <folder> <id>"
  echo "       ./runnable.sh .                        -- Lists the runnable commands in . "
  echo "       ./runnable.sh tests                    -- Lists the runnable commands in tests "
  echo ""
  echo "  Generatng the doctest.sh file"
  echo "       ./runnable.sh tests  00             -- generates the test script file containing all commands for the purpose of testing documentation"
  echo "       ./runnable.sh tests  00  -r         -- runs the script file above."
else
  if [ -z "$CMDID" ]; then
    grep "$ " "$1"/README.md | awk -F '[$][ ]' '{ print $0 }'
  elif [ "$CMDID" = "00" ]; then
    echo "Generating... [" doctest.sh "]"
    grep "$ " $FOLDER/README.md | awk -F '[$][ ]' '{
      print ""
      print "echo ========================="
      print "echo " $0
      print "echo ------------------------"
      print $2
     }' > doctest.sh
    chmod 700 doctest.sh
    if [ -z "$RUN" ]; then
      if [ "$RUN" = "-r" ]; then
         echo "Executing... [" doctest.sh "]"
        ./doctest.sh
      fi
    fi
  else
    CMND=`grep "$ " "$1"/README.md | grep "$CMDID" | awk -F '[$][ ]' '{ print $2 }'`
    echo "Running... [" $FOLDER "]/[" $CMND "]"
    eval $CMND
  fi
fi

Feel free to copy and customise as needed. Drop me a comment below with feedback.

Original project on github: https://github.com/munafsheikh/runnable