Merge pull request #476 from NLeSC/456_online_documentation

456-make online documentation optional

Author: fdiblen

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+* Make online documentation optional [#476](https://github.com/NLeSC/python-template/pull/476)
 * Added Python 3.12 support [#356](https://github.com/NLeSC/python-template/issues/356)
 * Template unit tests for documentation generation, linting and version bumping
 * Docstring for function

copier.yml

@@ -83,6 +83,12 @@ AddGitHubActions:
   default: "{{ template_profile != 'minimum' }}"
   help: GitHub actions to test the package and the documentation
 
+AddOnlineDocumentation:
+  when: "{{ template_profile == 'ask' }}"
+  type: bool
+  default: "{{ template_profile != 'minimum' }}"
+  help: Online documentation using Read the Docs
+
 
 # internal fields
 _subdirectory: template

…ithub/next_steps/03_readthedocs.md.jinja …ion %}03_readthedocs.md{% endif %}.jinjatemplate/.github/next_steps/03_readthedocs.md.jinja renamed to template/.github/next_steps/{% if AddOnlineDocumentation %}03_readthedocs.md{% endif %}.jinja template/.github/next_steps/03_readthedocs.md.jinja renamed to template/.github/next_steps/{% if AddOnlineDocumentation %}03_readthedocs.md{% endif %}.jinja

@@ -23,13 +23,6 @@ jobs:
         with:
           filename: .github/next_steps/02_citation.md
         id: citation
-      - name: Create readthedocs issue
-        uses: JasonEtco/create-an-issue@v2
-        env:
-          GITHUB_TOKEN: ${{ '{{ ' -}} secrets.GITHUB_TOKEN }}
-        with:
-          filename: .github/next_steps/03_readthedocs.md
-        id: readthedocs
       - name: Create Zenodo integration issue
         uses: JasonEtco/create-an-issue@v2
         env:
@@ -49,7 +42,6 @@ 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 }}
-          * 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

template/.github/workflows/next_steps.yml

@@ -0,0 +1,29 @@
+on: [push]
+permissions:
+  contents: write
+  issues: write
+name: Create an issue for online documentation
+jobs:
+  next_steps:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create readthedocs issue
+        uses: JasonEtco/create-an-issue@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          filename: .github/next_steps/03_readthedocs.md
+        id: readthedocs
+      - name: List created issues
+        run: |
+          echo 'Created issues that must be completed to have fully working Python package:
+          * Read the Docs instructions ${{ steps.readthedocs.outputs.url }}'
+      - name: Cleanup files needed to create next steps issues
+        run: |
+          git config --global user.name 'NLeSC Python template'
+          git config --global user.email '[email protected]'
+          git rm .github/workflows/next_steps_online_documentation.yml
+          git rm -r .github/next_steps
+          git commit -am "Cleanup automated next steps issue generator"
+          git push

template/.github/workflows/{% if AddOnlineDocumentation %}next_steps_online_documentation.yml{% endif %}

@@ -13,7 +13,9 @@
 | **Other best practices**           |   |
 | Static analysis                    | [![workflow scq badge](https://sonarcloud.io/api/project_badges/measure?project={{github_organization}}_{{package_name}}&metric=alert_status)](https://sonarcloud.io/dashboard?id={{github_organization}}_{{package_name}}) |
 | Coverage                           | [![workflow scc badge](https://sonarcloud.io/api/project_badges/measure?project={{github_organization}}_{{package_name}}&metric=coverage)](https://sonarcloud.io/dashboard?id={{github_organization}}_{{package_name}}) |
+{% if AddOnlineDocumentation -%}
 | Documentation                      | [![Documentation Status](https://readthedocs.org/projects/{{package_name}}/badge/?version=latest)](https://{{package_name}}.readthedocs.io/en/latest/?badge=latest) |
+{%- endif -%}
 | **GitHub Actions**                 |   |
 | Build                              | [![build]({{repository_url}}/actions/workflows/build.yml/badge.svg)]({{repository_url}}/actions/workflows/build.yml) |
 | Citation data consistency          | [![cffconvert]({{repository_url}}/actions/workflows/cffconvert.yml/badge.svg)]({{repository_url}}/actions/workflows/cffconvert.yml) |

template/README.md.jinja

@@ -59,7 +59,7 @@ help you decide which tool to use for packaging.
 - The documentation is set up with the ReadTheDocs Sphinx theme.
   - Check out its [configuration options](https://sphinx-rtd-theme.readthedocs.io/en/latest/).
 - [AutoAPI](https://sphinx-autoapi.readthedocs.io/) is used to generate documentation for the package Python objects.
-- `.readthedocs.yaml` is the ReadTheDocs configuration file. When ReadTheDocs is building the documentation this package and its development dependencies are installed so the API reference can be rendered.
+{% if AddOnlineDocumentation %}- `.readthedocs.yaml` is the ReadTheDocs configuration file. When ReadTheDocs is building the documentation this package and its development dependencies are installed so the API reference can be rendered.{% endif -%}
 - [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=writingdocumentation)
 
 ## Coding style conventions and code quality