feat(pckge): Add Read the Docs option to README #161 (#162)

A clickable document status badge improves the user's experience and
communicates the document status.

closes #161

README.rst

@@ -76,6 +76,7 @@ Features
 #. Documentation is in the process of being refreshed and organised into the
    `Diataxis`_ documentation framework.
 #. `Sphinx`_ docs: Documentation ready for generation with, for example, `Read the Docs`_.
+#. Optional to use to use a `Read the Docs`_ badge to communicate quickly.
 #. Auto-release to `PyPI`_ when you push a new tag to main (optional). Coming soon.
 #. Use commit tags to release to `Test-PyPi`_. Coming soon.
 #. An optional Command line interface using Click or Argparse.
@@ -85,18 +86,11 @@ Features
    will simultaneously add it to your local git config file.
 #. Optional to use to use a `Repo Status`_ badge to communicate quickly.
 
+
 .. note::
 
    Initialise your local git requires Git v2.33.0 or above.
 
-.. _Cookiecutter: https://github.com/cookiecutter/cookiecutter
-.. _cookiecutter-pypackage: https://github.com/audreyfeldroy/cookiecutter-pypackage
-.. _Projects: https://github.com/imAsparky/cookiecutter-py3-package/projects
-.. _CHANGELOG: https://github.com/imAsparky/cookiecutter-py3-package/blob/main/docs/source/CHANGELOG.md
-.. _Test-PyPi: https://test.pypi.org/
-.. _Conventional-Commits:  https://www.conventionalcommits.org/en/v1.0.0/
-.. _Diataxis: https://diataxis.fr/
-.. _Repo Status: https://www.repostatus.org/
 
 Quickstart
 ----------
@@ -162,16 +156,24 @@ Or Submit a Pull Request
 I also accept pull requests on this, if they're small, atomic, and if they
 make my own packaging experience better.
 
-.. _Tox: http://testrun.org/tox/
-.. _Sphinx: http://sphinx-doc.org/
-.. _Read the Docs: https://readthedocs.io/
-.. _`pyup.io`: https://pyup.io/
-.. _Punch: https://github.com/lgiordani/punch
+
+.. _CHANGELOG: https://github.com/imAsparky/cookiecutter-py3-package/blob/main/docs/source/CHANGELOG.md
+.. _cookiecutter-py3-pypackage tutorial: https://cookiecutter-py3-package.readthedocs.io/en/latest/tutorial.html
+.. _Cookiecutter: https://github.com/cookiecutter/cookiecutter
+.. _cookiecutter-pypackage: https://github.com/audreyfeldroy/cookiecutter-pypackage
+.. _Conventional-Commits:  https://www.conventionalcommits.org/en/v1.0.0/
+.. _Diataxis: https://diataxis.fr/
+.. _Mkdocs: https://pypi.org/project/mkdocs/
 .. _Poetry: https://python-poetry.org/
+.. _Projects: https://github.com/imAsparky/cookiecutter-py3-package/projects
 .. _PyPi: https://pypi.python.org/pypi
-.. _Mkdocs: https://pypi.org/project/mkdocs/
+.. _pyup.io: https://pyup.io/
 .. _quickstart: https://cookiecutter-py3-package.readthedocs.io/en/latest/how-to/how-to-quickstart.html
-.. _cookiecutter-py3-pypackage tutorial: https://cookiecutter-py3-package.readthedocs.io/en/latest/tutorial.html
+.. _Read the Docs: https://readthedocs.io/
+.. _Repo Status: https://www.repostatus.org/
+.. _Sphinx: http://sphinx-doc.org/
+.. _Test-PyPi: https://test.pypi.org/
+.. _Tox: http://testrun.org/tox/
 
 
 .. _`ardydedase/cookiecutter-pypackage`: https://github.com/ardydedase/cookiecutter-pypackage

cookiecutter.json

@@ -10,6 +10,7 @@
   "version": "0.1.0",
   "use_repo_status_badge": ["no", "concept", "wip", "active"],
   "add_pyup_badge": "n",
+  "use_readthedocs": ["y", "n"],
   "command_line_interface": ["Click", "Argparse", "No command-line interface"],
   "create_author_file": "y",
   "create_conventional_commits_edit_message": "y",

docs/source/reference/reference-project-inputs.rst

@@ -79,7 +79,21 @@ project.
 **add_pyup_badge**
   *default = n*
 
-  Whether to include a `pyup <https://github.com/pyupio/pyup>`_ badge.
+  Keep your open source package Python dependencies secure, up-to-date &
+  compliant for free with `Pyup <https://github.com/pyupio/pyup>`_.
+  This badge will advertise your security level.
+
+  Requires a free Pyup account.
+
+**use_readthedocs**
+  *default = y*
+
+  Host your open source package documentation for free with
+  `Read the Docs <https://readthedocs.org/>`_ and this badge will provide a
+  link to your documentation.
+
+  Requires a free Read the Docs account.
+
 
 **command_line_interface**
   *default = Click*

tests/test_bake_project.py

@@ -5,7 +5,6 @@
 import os
 import shlex
 import subprocess  # nosec
-import sys
 from contextlib import contextmanager
 from click.testing import CliRunner
 from cookiecutter.utils import rmtree
@@ -401,6 +400,23 @@ def test_bake_with_repo_automatic_testing_suite(cookies):
         assert "test_contribution.yaml" in test_workflow_with_files
 
 
+def test_baked_readme_with_readthedocs_badge(cookies):
+    """Test README file has a readthedocs badge generated."""
+    with bake_in_temp_dir(cookies, extra_context={"use_readthedocs": "y"}) as result:
+
+        assert " :alt: Documentation Status" in result.project.join("README.rst").read()
+
+
+def test_baked_readme_without_readthedocs_badge(cookies):
+    """Test README file has no readthedocs badge generated."""
+    with bake_in_temp_dir(cookies, extra_context={"use_readthedocs": "n"}) as result:
+
+        assert (
+            " :alt: Documentation Status"
+            not in result.project.join("README.rst").read()
+        )
+
+
 def test_baked_readme_with_repo_status_badge(cookies):
     """Test README file has a repo status badge generated."""
     with bake_in_temp_dir(

{{cookiecutter.git_project_name}}/README.rst

@@ -15,6 +15,13 @@
    :alt: Updates
 {%- endif %}
 
+{%- if cookiecutter.use_readthedocs == "y" %}
+.. image:: https://readthedocs.org/projects/{{cookiecutter.git_project_name}}/badge/?version=latest
+   :target: https://{{cookiecutter.git_project_name}}.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
+{%- endif %}
+
+
 
 
 {{ cookiecutter.project_short_description }}