Merge pull request #253 from NLeSC/237-rtd-next-step

Read the Docs next steps issue

Author: sverhoeven

{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md

@@ -1,5 +1,20 @@
 ---
-title: 'Next step: readthedocs'
+title: 'Next step: Read the Docs'
 ---
 
-Readthedocs instructions.
+Your Python package should have publicly available documentation, including API documentation for your users.
+[Read the Docs](https://readthedocs.org) can host your user documentation for you.
+
+To host the documentation of this repository please perform the following instructions:
+
+1. go to [Read the Docs](https://readthedocs.org/dashboard/import/?)
+1. log in with your GitHub account
+1. find `{{ cookiecutter.github_organization }}/{{ cookiecutter.project_name }}` in list and press `+` button.
+   * If repository is not listed,
+      1. go to [Read the Docs GitHub app](https://github.com/settings/connections/applications/fae83c942bc1d89609e2)
+      2. make sure {{ cookiecutter.github_organization }} has been granted access.
+      3. reload repository list on Read the Docs import page
+1. wait for the first build to be completed at <https://readthedocs.org/projects/{{ cookiecutter.project_name }}/builds>
+1. check that the link of the documentation badge in the [README.md]({{ cookiecutter.repository }}) works
+
+See [README.dev.md#]({{cookiecutter.repository}}/blob/main/README.dev.md#generating-the-api-docs) how to build documentation site locally.

{{cookiecutter.project_name}}/.github/workflows/next_steps.yml

@@ -45,7 +45,7 @@ jobs:
           echo 'Created issues that must be completed to have fully working Python package:
           * Sonarcloud integration ${{ steps.sonarcloud.outputs.url }}
           * Zenodo integration ${{ steps.zenodo.outputs.url }}
-          * Readthedocs instructions ${{ steps.readthedocs.outputs.url }}
+          * Read the Docs instructions ${{ steps.readthedocs.outputs.url }}
           * Citation data ${{ steps.citation.outputs.url }}
           * Linting fixes ${{ steps.linting.outputs.url }}'
       - name: Cleanup files needed to create next steps issues

{{cookiecutter.project_name}}/README.md

@@ -9,10 +9,11 @@
 | (3/5) community registry           | [![RSD](https://img.shields.io/badge/rsd-{{cookiecutter.project_name}}-00a3e3.svg)](https://www.research-software.nl/software/{{cookiecutter.project_name}}) [![workflow pypi badge](https://img.shields.io/pypi/v/{{cookiecutter.project_name}}.svg?colorB=blue)](https://pypi.python.org/project/{{cookiecutter.project_name}}/) |
 | (4/5) citation                     | [![DOI](https://zenodo.org/badge/DOI/<replace-with-created-DOI>.svg)](https://doi.org/<replace-with-created-DOI>) |
 | (5/5) checklist                    | [![workflow cii badge](https://bestpractices.coreinfrastructure.org/projects/<replace-with-created-project-identifier>/badge)](https://bestpractices.coreinfrastructure.org/projects/<replace-with-created-project-identifier>) |
-| howfairis                            | [![fair-software badge](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu) |
+| howfairis                          | [![fair-software badge](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu) |
 | **Other best practices**           | &nbsp; |
-| Static analysis              | [![workflow scq badge](https://sonarcloud.io/api/project_badges/measure?project={{cookiecutter.github_organization}}_{{cookiecutter.project_name}}&metric=alert_status)](https://sonarcloud.io/dashboard?id={{cookiecutter.github_organization}}_{{cookiecutter.project_name}}) |
-| Coverage              | [![workflow scc badge](https://sonarcloud.io/api/project_badges/measure?project={{cookiecutter.github_organization}}_{{cookiecutter.project_name}}&metric=coverage)](https://sonarcloud.io/dashboard?id={{cookiecutter.github_organization}}_{{cookiecutter.project_name}}) |
+| Static analysis                    | [![workflow scq badge](https://sonarcloud.io/api/project_badges/measure?project={{cookiecutter.github_organization}}_{{cookiecutter.project_name}}&metric=alert_status)](https://sonarcloud.io/dashboard?id={{cookiecutter.github_organization}}_{{cookiecutter.project_name}}) |
+| Coverage                           | [![workflow scc badge](https://sonarcloud.io/api/project_badges/measure?project={{cookiecutter.github_organization}}_{{cookiecutter.project_name}}&metric=coverage)](https://sonarcloud.io/dashboard?id={{cookiecutter.github_organization}}_{{cookiecutter.project_name}}) |
+| Documentation                      | [![Documentation Status](https://readthedocs.org/projects/{{cookiecutter.project_name}}/badge/?version=latest)](https://{{cookiecutter.project_name}}.readthedocs.io/en/latest/?badge=latest) |
 | **GitHub Actions**                 | &nbsp; |
 | Build                              | [![build]({{cookiecutter.repository}}/actions/workflows/build.yml/badge.svg)]({{cookiecutter.repository}}/actions/workflows/build.yml) |
 |  Metadata consistency              | [![cffconvert]({{cookiecutter.repository}}/actions/workflows/cffconvert.yml/badge.svg)]({{cookiecutter.repository}}/actions/workflows/cffconvert.yml) |

{{cookiecutter.project_name}}/project_setup.md

@@ -58,10 +58,6 @@ help you decide which tool to use for packaging.
   - [Google style docstring examples](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
 - The documentation is set up with the ReadTheDocs Sphinx theme.
   - Check out its [configuration options](https://sphinx-rtd-theme.readthedocs.io/en/latest/).
-- To generate HTML documentation, run `make html` in the `docs/` folder.
-- To put the documentation on [ReadTheDocs](https://readthedocs.org), log in to your ReadTheDocs account, and import
-  the repository (under 'My Projects').
-  - Include the link to the documentation in your project's [README.md](README.md).
 - [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=writingdocumentation)
 
 ## Coding style conventions and code quality