Workaround to include relative readme into docs directory

The workaround is described in
readthedocs/recommonmark#191

It is not perfect, but it does the job

README.md

@@ -20,7 +20,7 @@ the main documentation files still use reStructuredText by default.
 
 Remember to install [wheel] version 0.31 or higher and use [twine] to upload your
 package to [PyPI] instead of `python setup.py release` for this to work, e.g.:
-```commandline
+```bash
 python setup.py sdist bdist_wheel
 twine upload dist/*
 ```
@@ -32,15 +32,15 @@ twine upload dist/*
 This project uses [pre-commit], please make sure to install it before making any
 changes:
 
-```commandline
+```bash
 pip install pre-commit
 cd pyscaffoldext-markdown
 pre-commit install
 ```
 
 It is a good idea to update the hooks to the latest version:
 
-```commandline
+```bash
 pre-commit autoupdate
 ```
 

docs/conf.py

@@ -87,17 +87,25 @@
 # To configure AutoStructify
 def setup(app):
     from recommonmark.transform import AutoStructify
+    from m2r import MdInclude, convert
 
     params = {
         "auto_toc_tree_section": "Contents",
         "enable_eval_rst": True,
-        "enable_auto_doc_ref": 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"}
@@ -166,7 +174,7 @@ def setup(app):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 
 # 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

docs/index.rst

@@ -2,25 +2,8 @@
 pyscaffoldext-markdown
 ======================
 
-This is the documentation of **pyscaffoldext-markdown**.
-
-.. note::
-
-    This is the main page of your project's `Sphinx`_ documentation.
-    It is formatted in `reStructuredText`_. Add additional pages
-    by creating rst-files in ``docs`` and adding them to the `toctree`_ below.
-    Use then `references`_ in order to link them from this page, e.g.
-    :ref:`authors` and :ref:`changes`.
-
-    It is also possible to refer to the documentation of other Python packages
-    with the `Python domain syntax`_. By default you can reference the
-    documentation of `Sphinx`_, `Python`_, `NumPy`_, `SciPy`_, `matplotlib`_,
-    `Pandas`_, `Scikit-Learn`_. You can add more by extending the
-    ``intersphinx_mapping`` in your Sphinx's ``conf.py``.
-
-    The pretty useful extension `autodoc`_ is activated by default and lets
-    you include documentation from docstrings. Docstrings can be written in
-    `Google style`_ (recommended!), `NumPy style`_ and `classical style`_.
+PyScaffold_ extension which replaces reStructuredText_ formatted files
+by Markdown_ format except for Sphinx_-related files.
 
 
 Contents
@@ -29,6 +12,7 @@ Contents
 .. toctree::
    :maxdepth: 2
 
+   Quickstart <readme>
    License <license>
    Authors <authors>
    Changelog <changelog>
@@ -42,18 +26,7 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
-.. _toctree: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
+.. _PyScaffold: http://pyscaffold.org
 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
-.. _references: http://www.sphinx-doc.org/en/stable/markup/inline.html
-.. _Python domain syntax: http://sphinx-doc.org/domains.html#the-python-domain
+.. _Markdown: https://daringfireball.net/projects/markdown/
 .. _Sphinx: http://www.sphinx-doc.org/
-.. _Python: http://docs.python.org/
-.. _Numpy: http://docs.scipy.org/doc/numpy
-.. _SciPy: http://docs.scipy.org/doc/scipy/reference/
-.. _matplotlib: https://matplotlib.org/contents.html#
-.. _Pandas: http://pandas.pydata.org/pandas-docs/stable
-.. _Scikit-Learn: http://scikit-learn.org/stable
-.. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
-.. _Google style: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
-.. _NumPy style: https://numpydoc.readthedocs.io/en/latest/format.html
-.. _classical style: http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists

docs/readme.rst

@@ -0,0 +1,2 @@
+.. _readme:
+.. mdinclude:: ../README.md

docs/requirements.txt

@@ -1,6 +1,7 @@
 # Requirements file for ReadTheDocs, check .readthedocs.yml.
 # To build the module reference correctly, make sure every external package
 # under `install_requires` in `setup.cfg` is also listed here!
+m2r
 recommonmark
 sphinx>=3.2.1
 sphinx_rtd_theme