feat(m2r): use m2r to convert automatic .md files to .rst

* https://github.com/miyakogi/m2r
  - Markdown to reStructuredText converter

.gitignore

@@ -101,3 +101,6 @@ ENV/
 
 # mypy
 .mypy_cache/
+
+# copied `.md` files used for conversion to `.rst` using `m2r`
+docs/*.md

docs/index.rst

@@ -8,7 +8,7 @@ Welcome to template-formula's documentation!
 ============================================
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :caption: Contents
    :numbered:
    :glob:
@@ -16,3 +16,5 @@ Welcome to template-formula's documentation!
    README <README>
    CONTRIBUTING
    TOFS_pattern
+   AUTHORS
+   CHANGELOG

release.config.js

@@ -14,7 +14,7 @@ module.exports = {
         prepareCmd: 'sh ./update_FORMULA.sh ${nextRelease.version}',
       }],
       ['@semantic-release/git', {
-        assets: ['*.md', 'FORMULA'],
+        assets: ['*.md', 'docs/*.rst', 'FORMULA'],
       }],
       '@semantic-release/github',
   ],

update_FORMULA.sh

@@ -1,2 +1,30 @@
 #!/bin/sh
+
+###############################################################################
+# (A) Update `FORMULA` with `${nextRelease.version}`
+###############################################################################
 sed -i -e "s_^\(version:\).*_\1 ${1}_" FORMULA
+
+
+###############################################################################
+# (B) Use `m2r` to convert automatically produced `.md` docs to `.rst`
+###############################################################################
+
+# Install `m2r`
+sudo -H pip install m2r
+
+# Copy and then convert the `.md` docs
+cp *.md docs/
+cd docs/
+m2r --overwrite *.md
+
+# Change excess `H1` headings to `H2` in converted `CHANGELOG.rst`
+sed -i -e '/^=.*$/s/=/-/g' CHANGELOG.rst
+sed -i -e '1,4s/-/=/g' CHANGELOG.rst
+
+# Use for debugging output, when required
+# cat AUTHORS.rst
+# cat CHANGELOG.rst
+
+# Return back to the main directory
+cd ..