Add mermaid diagram support to documentation site build

So that we can add a relationship diagram to the central data structures
documentation page.

Author: thomasspriggs

.github/workflows/publish.yaml

@@ -10,11 +10,14 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Install doxygen
-        run: sudo apt install doxygen graphviz pandoc
+        run: sudo apt install doxygen graphviz pandoc npm
 
       - name: Install python modules
         run: sudo python3 -m pip install gitpython pandocfilters
 
+      - name: Install mermaid diagram filter
+        run: sudo npm install --global mermaid-filter
+
       - name: Build documentation
         run: cd doc/doxygen-root && make && touch html/.nojekyll
 

doc/doxygen-root/doxygen-markdown/markdown.sh

@@ -34,6 +34,21 @@ $BINDIR/append-last-modified-dates.py $FILES
 #         $BINDIR/pandoc-codeblock-repair.sh > $file
 # done
 
+echo
+echo "Rendering mermaid diagrams"
+FILES=$(grep --include=\*.md -rl . -e "\`\`\`mermaid")
+for file in $FILES; do
+    echo $file
+    tmp=/tmp/${file%.*}2.md
+    mkdir -p $(dirname $tmp)
+    cp $file $tmp
+    # Note that gfm is GitHub Flavour Markdown. The double \\ at the start of
+    # lines is unescaped using sed in order to fix doxygen tags, which are
+    # broken by pandoc.
+    pandoc --read=gfm --write=gfm --wrap=none --filter=mermaid-filter $tmp |
+        $BINDIR/pandoc-codeblock-repair.sh | sed 's/^\\\\/\\/' > $file
+done
+
 cprovers=$(find . -name cprover-manual)
 cprover=${cprovers[0]}
 
@@ -49,7 +64,7 @@ echo "Running pandoc filter over cprover-manual markdown files"
 FILES=$(find $cprover -name '*.md')
 for file in $FILES; do
     echo $file
-    tmp=/tmp/${file%.*}2.md
+    tmp=/tmp/${file%.*}3.md
     mkdir -p $(dirname $tmp)
     cp $file $tmp
     pandoc  --write=markdown_phpextra --wrap=none --filter=$BINDIR/pandoc-cprover-link-filter.py $tmp |