Markdown everywhere

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Updated system tests/CI using `pyscaffoldext-custom-extension`
 - Simplified templates package thanks to `pyscaffold.templates.get_template`
 - Removed unnecessary `coding: utf-8` comments
+- Use symlinks to load `README.md`, `AUTHORS.md`, `CHANGELOG.md` into Sphinx, issues #6, #7.
 
 ## Version 0.3.2
 

README.md

@@ -1,4 +1,5 @@
 [![Build Status](https://api.cirrus-ci.com/github/pyscaffold/pyscaffoldext-markdown.svg?branch=master)](https://cirrus-ci.com/github/pyscaffold/pyscaffoldext-markdown)
+[![ReadTheDocs](https://readthedocs.org/projects/pyscaffoldext-markdown/badge/?version=latest)](https://pyscaffoldext-markdown.readthedocs.io/)
 [![Coveralls](https://img.shields.io/coveralls/github/pyscaffold/pyscaffoldext-markdown/master.svg)](https://coveralls.io/r/pyscaffold/pyscaffoldext-markdown)
 [![PyPI-Server](https://img.shields.io/pypi/v/pyscaffoldext-markdown.svg)](https://pypi.org/project/pyscaffoldext-markdown)
 [![Downloads](https://pepy.tech/badge/pyscaffoldext-markdown/month)](https://pepy.tech/project/pyscaffoldext-markdown)
@@ -7,22 +8,65 @@
 # pyscaffoldext-markdown
 
 [PyScaffold] extension which replaces [reStructuredText] formatted files
-by [Markdown] format except for Sphinx-related files.
+by [Markdown] format except for [Sphinx]-related files.
+
 
 ## Usage
 
 Just install this package with `pip install pyscaffoldext-markdown`
 and note that `putup -h` shows a new option `--markdown`.
 Basically this extension will replace `README.rst` by a proper `README.md` and
 activate the support of Markdown files in Sphinx.
-Due to limitations of the Markdown syntax compared to reStructuredText,
-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.:
+
+## Limitations
+
+Due to limitations of the Markdown syntax compared to [reStructuredText],
+it is necessary to use symbolic links (and some reStructuredText files) to
+avoid keeping multiple copies of files (such as `CHANGELOG.md`) meant to be
+placed at the root of the repository but included in the documentation
+generated by [Sphinx]. If you are a Windows user please make sure to configure
+your system accordingly. The following references might be helpful:
+
+*Symbolic links on Windows*
+
+- [http://github.com/git-for-windows/git/wiki/Symbolic-Links](http://github.com/git-for-windows/git/wiki/Symbolic-Links)
+- [https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/)
+- [https://docs.microsoft.com/en-us/windows/win32/fileio/creating-symbolic-links](https://docs.microsoft.com/en-us/windows/win32/fileio/creating-symbolic-links)
+
+*Markdown limitations*
+
+- [https://github.com/readthedocs/recommonmark/issues/191](https://github.com/readthedocs/recommonmark/issues/191)
+- [https://github.com/sphinx-doc/sphinx/issues/701](https://github.com/sphinx-doc/sphinx/issues/701)
+- [https://github.com/sphinx-doc/sphinx/pull/7739](https://github.com/sphinx-doc/sphinx/pull/7739)
+
+Windows users that still face problems after configuring their systems for
+symbolic links might want to attempt [WSL] or decide to stick with [reStructuredText]
+for (problematic) parts of their documentation files.
+
+
+## Building and Releasing
+
+By default, the [tox] configuration generated by [PyScaffold] is compatible
+with Markdown (as implemented in this extension). This means that (after
+installing [tox] with [pip] or [pipx]) you can run:
+
+```bash
+tox -e docs  # to build your documentation
+tox -e publish  # to test your project uploads correctly in test.pypi.org
+tox -e publish -- --repository pypi  # to release your package to PyPI
+tox -av  # to list all the tasks available
+```
+
+Please remember that the command `python setup.py release` is no longer
+recommended, so if you don't like [tox], please consider using
+[Sphinx] and [twine] directly:
+
 ```bash
-python setup.py sdist bdist_wheel
-twine upload dist/*
+python -m pip install -U pip setuptools wheel sphinx twine
+python setup.py bdist_wheel  # to build your package distributions
+make -C docs html  # to build your docs
+twine upload dist/*  # to release your package to PyPI
 ```
 
 <!-- pyscaffold-notes -->
@@ -49,14 +93,18 @@ Please also check PyScaffold's [contribution guidelines].
 
 ## Note
 
-This project has been set up using PyScaffold 3.2. For details and usage
-information on PyScaffold see https://pyscaffold.org/.
+This project has been set up using PyScaffold 4.0. For details and usage
+information on PyScaffold see [https://pyscaffold.org/](https://pyscaffold.org/).
 
 [PyScaffold]: https://pyscaffold.org
 [reStructuredText]: http://docutils.sourceforge.net/rst.html
 [Markdown]: https://daringfireball.net/projects/markdown/
+[Sphinx]: http://www.sphinx-doc.org/
+[WSL]: https://docs.microsoft.com/en-us/windows/wsl/
+[tox]: https://tox.readthedocs.org/
+[pip]: https://pip.pypa.io/en/stable/
+[pipx]: https://pipxproject.github.io/pipx/
 [twine]: https://twine.readthedocs.io/
 [PyPI]: https://pypi.org/
-[wheel]: https://wheel.readthedocs.io/
 [pre-commit]: http://pre-commit.com/
 [contribution guidelines]: https://pyscaffold.org/en/latest/contributing.html

docs/conf.py

@@ -90,6 +90,7 @@ def setup(app):
     from recommonmark.transform import AutoStructify
 
     params = {
+        "enable_auto_toc_tree": True,
         "auto_toc_tree_section": "Contents",
         "auto_toc_maxdepth": 2,
         "enable_eval_rst": True,

docs/license.rst

@@ -1,3 +1,9 @@
+..
+  Files added to Sphinx' TOC need to have titles, otherwise are ignored.
+  Since the license is a .txt file, its title is not parsed/recognised.
+  Therefore, we need a new file with a title and the ``include`` directive.
+  The ``include`` directive is only available in .rst files.
+
 .. _license:
 
 =======

setup.cfg

@@ -47,13 +47,13 @@ package_dir =
     =src
 
 # Require a min/specific Python version (comma-separated conditions)
-# python_requires = >=3.8
+python_requires = >=3.6
 
 # Add here dependencies of your project (line-separated)
 # TODO: Remove conditional dependencies according to `python_requires` above
 install_requires =
     importlib-metadata; python_version<"3.8"
-    pyscaffold>=4.0b2,<5.0a0
+    pyscaffold>=4.0b3,<5.0a0
     wheel>=0.31
     recommonmark