Replace m2r workaround with 'blessed approach'

The approach used by recommonmark's own documentation is to include a
symbolic link file inside the `docs` directory, instead of trying to do
a `include`.

References:
readthedocs/recommonmark#191
sphinx-doc/sphinx#701
sphinx-doc/sphinx#7739

README.md

@@ -6,7 +6,7 @@
 
 # pyscaffoldext-markdown
 
-PyScaffold extension which replaces [reStructuredText] formatted files
+[PyScaffold] extension which replaces [reStructuredText] formatted files
 by [Markdown] format except for Sphinx-related files.
 
 ## Usage
@@ -52,6 +52,7 @@ Please also check PyScaffold's [contribution guidelines].
 This project has been set up using PyScaffold 3.2. For details and usage
 information on PyScaffold see https://pyscaffold.org/.
 
+[PyScaffold]: https://pyscaffold.org
 [reStructuredText]: http://docutils.sourceforge.net/rst.html
 [Markdown]: https://daringfireball.net/projects/markdown/
 [twine]: https://twine.readthedocs.io/

docs/conf.py

@@ -78,6 +78,7 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
+    "recommonmark",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -87,25 +88,17 @@
 # To configure AutoStructify
 def setup(app):
     from recommonmark.transform import AutoStructify
-    from m2r import MdInclude, convert
 
     params = {
         "auto_toc_tree_section": "Contents",
+        "auto_toc_maxdepth": 2,
         "enable_eval_rst": True,
-        # "enable_auto_doc_ref": True,
         "enable_math": True,
         "enable_inline_math": True,
     }
     app.add_config_value("recommonmark_config", params, True)
     app.add_transform(AutoStructify)
 
-    # from m2r to make `mdinclude` work
-    app.add_config_value('no_underscore_emphasis', False, 'env')
-    app.add_config_value('m2r_parse_relative_links', False, 'env')
-    app.add_config_value('m2r_anonymous_references', False, 'env')
-    app.add_config_value('m2r_disable_inline_math', False, 'env')
-    app.add_directive('mdinclude', MdInclude)
-
 
 # Additional parsers besides rst
 source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
@@ -179,7 +172,7 @@ def setup(app):
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {"sidebar_width": "300px", "page_width": "1200px"}
+# html_theme_options = {"sidebar_width": "300px", "page_width": "1200px"}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/readme.md

@@ -0,0 +1 @@
+../README.md