From 949ebd37aab1061ed4d1a50405c3595e10d93472 Mon Sep 17 00:00:00 2001 From: Stefan Verhoeven Date: Thu, 29 Apr 2021 13:48:46 +0200 Subject: [PATCH 1/5] Add badge for Read the Docs --- {{cookiecutter.project_name}}/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/{{cookiecutter.project_name}}/README.md b/{{cookiecutter.project_name}}/README.md index 49a68bfb..5bc654a3 100644 --- a/{{cookiecutter.project_name}}/README.md +++ b/{{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/.svg)](https://doi.org/) | | (5/5) checklist | [![workflow cii badge](https://bestpractices.coreinfrastructure.org/projects//badge)](https://bestpractices.coreinfrastructure.org/projects/) | -| 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** |   | -| 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** |   | | 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) | From 81662cf682bea29f548cd545239d9e16e91f8ecf Mon Sep 17 00:00:00 2001 From: Stefan Verhoeven Date: Thu, 29 Apr 2021 13:49:02 +0200 Subject: [PATCH 2/5] Write up Read the Docs instructions Refs #237 --- .../.github/next_steps/03_readthedocs.md | 19 +++++++++++++++++-- .../.github/workflows/next_steps.yml | 2 +- .../project_setup.md | 4 ---- 3 files changed, 18 insertions(+), 7 deletions(-) diff --git a/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md b/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md index 11b4c496..b0c64e3b 100644 --- a/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md +++ b/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md @@ -1,7 +1,22 @@ --- -title: 'Next step: readthedocs' +title: 'Next step: Read the Docs' labels: - 'action required' --- -Readthedocs instructions. +Your Python package should have publicly readable 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 +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. diff --git a/{{cookiecutter.project_name}}/.github/workflows/next_steps.yml b/{{cookiecutter.project_name}}/.github/workflows/next_steps.yml index 58303cd2..afad1bc6 100644 --- a/{{cookiecutter.project_name}}/.github/workflows/next_steps.yml +++ b/{{cookiecutter.project_name}}/.github/workflows/next_steps.yml @@ -51,7 +51,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 diff --git a/{{cookiecutter.project_name}}/project_setup.md b/{{cookiecutter.project_name}}/project_setup.md index a0308595..2419af3a 100644 --- a/{{cookiecutter.project_name}}/project_setup.md +++ b/{{cookiecutter.project_name}}/project_setup.md @@ -81,10 +81,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 From f084394c3b7ac65c17ee797e3a198215b7a20c45 Mon Sep 17 00:00:00 2001 From: Stefan Verhoeven Date: Thu, 29 Apr 2021 14:33:44 +0200 Subject: [PATCH 3/5] Update {{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md Co-authored-by: Faruk D. --- .../.github/next_steps/03_readthedocs.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md b/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md index b0c64e3b..64b2cbd7 100644 --- a/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md +++ b/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md @@ -1,7 +1,5 @@ --- title: 'Next step: Read the Docs' -labels: - - 'action required' --- Your Python package should have publicly readable documentation, including API documentation, for your users. From 6b3dd02b4954734c6fa024687ba8a2eeb1dd8d30 Mon Sep 17 00:00:00 2001 From: Stefan Verhoeven Date: Thu, 29 Apr 2021 14:35:11 +0200 Subject: [PATCH 4/5] Update {{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md Co-authored-by: Faruk D. --- .../.github/next_steps/03_readthedocs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md b/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md index 64b2cbd7..eb32b8d1 100644 --- a/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md +++ b/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md @@ -2,7 +2,7 @@ title: 'Next step: Read the Docs' --- -Your Python package should have publicly readable documentation, including API documentation, for your users. +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: From ba13329786786591deaa47c3cbd078398d290632 Mon Sep 17 00:00:00 2001 From: Stefan Verhoeven Date: Thu, 29 Apr 2021 14:47:25 +0200 Subject: [PATCH 5/5] Update {{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md Co-authored-by: Faruk D. --- .../.github/next_steps/03_readthedocs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md b/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md index eb32b8d1..1ad6bf26 100644 --- a/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md +++ b/{{cookiecutter.project_name}}/.github/next_steps/03_readthedocs.md @@ -13,7 +13,7 @@ To host the documentation of this repository please perform the following instru * 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 + 3. reload repository list on Read the Docs import page 1. wait for the first build to be completed at 1. check that the link of the documentation badge in the [README.md]({{ cookiecutter.repository }}) works