feat: Add facility to convert documents with pandoc

Add a facility to, with relative ease, create OpenDocument Text and
Word documents from the original Markdown. To use, run

tox -e to-odt -- -o output.odt input1.md input2.md input3.md

or

tox -e to-docx -- -o output.docx input1.md input2.md input3.md

To achieve this, a simple script concatenates the input files, processes
them against mkdocs.yml using the Jinja2 CLI, and feeds the result to
pandoc with appropriate command-line options.

For branding, reference.docx and reference.odt files can be placed
into the pandoc subdirectory.

Also, add bashate testing for the script itself.

Author: fghaas

.github/workflows/tox.yml

@@ -24,7 +24,7 @@ jobs:
         # necessary here, but for some reason tox invokes no testenvs
         # at all if invoked as just "tox" from the GitHub Actions
         # workflow. Until that is fixed, name the testenvs.
-        run: tox -e gitlint,yamllint,build
+        run: tox -e gitlint,yamllint,bashate,build
       - name: Upload build
         uses: actions/upload-artifact@v2
         with:

pandoc/README.md

@@ -0,0 +1,9 @@
+This directory is meant to be used as a Pandoc user data directory,
+i.e. something to be referenced with `pandoc`’s `--data-dir` option.
+
+This directory can include, among others,
+
+* a `reference.odt` template for use with `pandoc -t odt` (for
+  OpenDocument Text output, as used by LibreOffice),
+* a `reference.docx` template for use with `pandoc -t docx` (for
+  Microsoft Word documents).

scripts/from-markdown.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+#
+# from-markdown.sh — a wrapper script to convert Markdown to
+# Pandoc-supported output formats
+
+set -e
+
+usage() {
+    echo "Usage: $0 [-t format] [-o outfile] infile..." >&2
+}
+
+output="-"
+format="docx"
+
+while getopts "o:t:h" opt; do
+    case "${opt}" in
+        o)
+            output=${OPTARG}
+            ;;
+        t)
+            format=${OPTARG}
+            ;;
+        h)
+            usage
+            exit 0
+            ;;
+        *)
+            usage
+            exit 1
+            ;;
+    esac
+done
+shift $((OPTIND-1))
+
+# Concatenate all input files and preprocess them with Jinja2, then
+# feed the result to pandoc on stdin
+tempmd=`mktemp --suffix .md`
+cat $* > $tempmd
+jinja2 $tempmd mkdocs.yml \
+    | pandoc \
+        --data-dir=pandoc \
+        --no-highlight \
+        -f gfm \
+        -t ${format} \
+        -o ${output} \
+        -i -
+
+# Clean up
+rm $tempmd

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = yamllint,build
+envlist = yamllint,bashate,build
 
 [testenv]
 envdir = {toxworkdir}/mkdocs
@@ -33,6 +33,27 @@ commands =
 commands =
   mkdocs build --strict
 
+[testenv:bashate]
+envdir = {toxworkdir}/bashate
+deps =
+  bashate
+commands =
+  bashate {toxinidir}/scripts/from-markdown.sh
+
+[testenv:to-odt]
+envdir = {toxworkdir}/pandoc
+deps =
+  jinja2-cli[yaml]
+commands =
+  {toxinidir}/scripts/from-markdown.sh -t odt {posargs}
+
+[testenv:to-docx]
+envdir = {toxworkdir}/pandoc
+deps =
+  jinja2-cli[yaml]
+commands =
+  {toxinidir}/scripts/from-markdown.sh -t docx {posargs}
+
 [testenv:gitlint]
 envdir = {toxworkdir}/gitlint
 deps = gitlint