Merge branch 'feature/cpp-to-md' into 'master'

Automatically create READMEs for examples

See merge request !1683

bin/doc/cpp_to_md.sh

+#!/bin/sh
+
+# check if help is needed
+if test "$1" = "--help" || test "$1" = "-help" \
+   || test "$1" = "help" || test "$1" = ""; then
+  echo ""
+  echo "USAGE: $0 FILENAME"
+  echo ""
+  echo "The argument should be a C++ header or source file."
+  echo "The file is converted to Markdown and forwarded to stdout."
+  echo "In particular, a C++ comment is converted to its content,"
+  echo "while normal code is put into corresponding Markdown code blocks."
+  echo "Supposed to be called by the script merge_cpp_and_md.sh."
+  exit 0
+fi
+
+if [[ ${1: -3} == ".hh" ]]; then
+  sed '1,/#define/d' $1 >tmpfile
+  isheader=true
+else
+  sed '1,/\*\*\*\*\*\//d' $1 >tmpfile
+  isheader=false
+fi
+
+insidecodeblock=false
+lastline=""
+strippedlastline=""
+firstline=true
+
+while IFS= read -r line
+do
+  strippedline=$(echo $line | sed "s/^[ \t]*//")
+  if [[ $firstline == false ]]; then
+    if [[ ${strippedline:0:2} == "//" ]]; then
+      if [[ $insidecodeblock == true ]]; then
+        if [[ $lastline != "" ]]; then
+          echo "$lastline"
+        fi
+        echo "\`\`\`"
+        insidecodeblock=false
+      else
+        linetoprint=$(echo ${strippedlastline:2} | sed "s/^[ \t]*//")
+        echo "$linetoprint"
+      fi
+    else
+      if [[ $insidecodeblock == false  ]]; then
+        linetoprint=$(echo ${strippedlastline:2} | sed "s/^[ \t]*//")
+        echo "$linetoprint"
+        echo "\`\`\`cpp"
+        insidecodeblock=true
+      else
+        echo "$lastline"
+      fi
+    fi
+  else
+    if [[ ${strippedline:0:2} != "//" && $line != "" ]]; then
+      echo "\`\`\`cpp"
+      insidecodeblock=true
+    fi
+    firstline=false
+  fi
+  lastline="$line"
+  strippedlastline="$strippedline"
+done < tmpfile
+
+if [[ $isheader == false ]]; then
+  if [[ ${strippedlastline:0:2} == "//" ]]; then
+    if [[ $insidecodeblock == true ]]; then
+      echo "\`\`\`"
+      insidecodeblock=false
+    fi
+    linetoprint=$(echo ${strippedlastline:2} | sed "s/^[ \t]*//")
+    echo "$linetoprint"
+  else
+    if [[ $insidecodeblock == false  ]]; then
+      echo "\`\`\`cpp"
+      insidecodeblock=true
+    fi
+    echo "$lastline"
+  fi
+fi
+
+if [[ $insidecodeblock == true ]]; then
+  echo "\`\`\`"
+  insidecodeblock=false
+fi

bin/doc/merge_cpp_and_md.sh

+#!/bin/sh
+
+# check if help is needed
+if test "$1" = "--help" || test "$1" = "-help" \
+   || test "$1" = "help" || test "$1" = ""; then
+  echo ""
+  echo "USAGE: $0 FILENAME_1 [FILENAME_2 ...]"
+  echo ""
+  echo "The arguments should be names of Markdown and/or C++ files."
+  echo "The script loops through all arguments. If a Markdown file is encountered,"
+  echo "its content is forwarded to stdout. For another file, a Markdown header"
+  echo "stating the filename is printed and the script cpp_to_md.sh is applied."
+  echo "To be used for creating README.mds in the example folder. For example, by"
+  echo "bash $0 intro.md spatialparams.hh problem.hh main.cc results.md >README.md"
+  exit 0
+fi
+
+for filename in "$@"
+do
+  if [[ ${filename: -3} == ".md" ]]; then
+    cat $filename
+  else
+    echo ""
+    echo ""
+    echo "## The file \`$filename\`"
+    echo ""
+    bash cpp_to_md.sh $filename
+    echo ""
+  fi
+done