Coverage, badges and documentation updates (#18)

- Replace read-the-docs links with GitHub pages links
- Document project options, i.e questions asked when creating a project
- Remove references to CodeCov and replace with SonarCloud
- Support label skip-changelog
- Fix badges
- Fix SonarCloud coverage warning about unknown paths
- Set coverage limit to 80 %
- Replace old logo with Statistics Norway logo
- Update dependencies

.github/workflows/constraints.txt

@@ -3,6 +3,6 @@ cookiecutter==2.3.0
 cutty==0.18.0
 nox==2023.4.22
 nox-poetry==1.0.3
-poetry==1.5.1
+poetry==1.6.1
 pre-commit==3.3.3
-virtualenv==20.24.2
+virtualenv==20.24.4

README.md

@@ -6,9 +6,9 @@
 [![Python Version][python version badge]][github page]
 [![CalVer][calver badge]][calver]
 [![License][license badge]][license]<br>
-[![Read the documentation][readthedocs badge]][readthedocs page]
+[![Documentation][ghpages badge]][ghpages page]
 [![Tests][github actions badge]][github actions page]
-[![Codecov][codecov badge]][codecov page]<br>
+[![Coverage][sonarcov badge]][sonar page]<br>
 [![pre-commit enabled][pre-commit badge]][pre-commit project]
 [![Black codestyle][black badge]][black project]
 [![Contributor Covenant][contributor covenant badge]][code of conduct]
@@ -18,8 +18,8 @@
 [calver badge]: https://img.shields.io/badge/calver-YYYY.MM.DD-22bfda.svg
 [calver]: https://calver.org/
 [code of conduct]: https://github.com/statisticsnorway/ssb-pypitemplate/blob/main/CODE_OF_CONDUCT.md
-[codecov badge]: https://codecov.io/gh/cjolowicz/cookiecutter-hypermodern-python-instance/branch/main/graph/badge.svg
-[codecov page]: https://app.codecov.io/gh/cjolowicz/cookiecutter-hypermodern-python-instance
+[sonarcov badge]: https://sonarcloud.io/api/project_badges/measure?project=statisticsnorway_ssb-pypitemplate-instance&metric=coverage
+[sonar page]: https://sonarcloud.io/summary/overall?id=statisticsnorway_ssb-pypitemplate-instance
 [contributor covenant badge]: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
 [github actions badge]: https://github.com/statisticsnorway/ssb-pypitemplate/workflows/Tests/badge.svg
 [github actions page]: https://github.com/statisticsnorway/ssb-pypitemplate/actions?workflow=Tests
@@ -28,36 +28,53 @@
 [license]: https://opensource.org/licenses/MIT
 [pre-commit badge]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
 [pre-commit project]: https://pre-commit.com/
-[python version badge]: https://img.shields.io/pypi/pyversions/cookiecutter-hypermodern-python-instance
-[readthedocs badge]: https://img.shields.io/readthedocs/cookiecutter-hypermodern-python/latest.svg?label=Read%20the%20Docs
-[readthedocs page]: https://cookiecutter-hypermodern-python.readthedocs.io/
+[python version badge]: https://img.shields.io/pypi/pyversions/ssb-pypitemplate-instance
+[ghpages badge]: https://github.com/statisticsnorway/ssb-pypitemplate/actions/workflows/docs.yml/badge.svg
+[ghpages page]: https://statisticsnorway.github.io/ssb-pypitemplate/
 [status badge]: https://badgen.net/badge/status/beta/d8624d
 
 <!-- badges-end -->
 
-<p align="center"><img alt="logo" src="docs/_static/logo.png" width="50%" /></p>
+<p align="center"><img alt="logo" src="docs/_static/ssb_logo.svg" width="50%" /></p>
 
 [Cookiecutter] template for a Python package based on the
 [Hypermodern Python] article series.
 This repo is a fork of [cookiecutter-hypermodern-python], and adjusted for use
 in [Statistics Norway].
 
-✨📚✨ [Read the full documentation][readthedocs page]
+✨📚✨ [Read the full documentation][ghpages page]
+
+- [Quickstart]
+- [User Guide]
 
 [cookiecutter]: https://github.com/cookiecutter/cookiecutter
 [hypermodern python]: https://medium.com/@cjolowicz/hypermodern-python-d44485d9d769
 [cookiecutter-hypermodern-python]: https://github.com/cjolowicz/cookiecutter-hypermodern-python.git
-[statistics norway]: https://www.ssb.no/
+[statistics norway]: https://www.ssb.no/en
+[quickstart]: https://statisticsnorway.github.io/ssb-pypitemplate/quickstart.html
+[user guide]: https://statisticsnorway.github.io/ssb-pypitemplate/guide.html
 
 ## Usage
 
 Use [Cruft] to create and update an instance of this template.
 
 ```console
 cruft create https://github.com/statisticsnorway/ssb-pypitemplate.git --checkout=2023.2.24
+```
+
+Cruft downloads the template, and asks you a series of questions about project variables,
+for example, how you wish your project to be named. Further details and a complete list of
+project variables with explanation can be found in the [Creating a project] section of the
+user guide.
+
+[creating a project]: https://statisticsnorway.github.io/ssb-pypitemplate/guide.html#creating-a-project
 
-# To check if there are there are template updates and update your instance with
-# the new updates, run the following commands from the root directory:
+### Update
+
+To check if there are there are template updates and update your instance with
+the new updates, run the following commands from the root directory:
+
+```console
 cruft check
 cruft update
 ```

docs/conf.py

@@ -9,7 +9,7 @@
 intersphinx_mapping = {"mypy": ("https://mypy.readthedocs.io/en/stable/", None)}
 language = "en"
 html_theme = "furo"
-html_logo = "_static/logo.png"
+html_logo = "_static/ssb_logo.svg"
 linkcheck_ignore = [
     "codeofconduct.html",
     "https://github.com/PyCQA/flake8-bugbear#",

docs/guide.md

@@ -217,10 +217,10 @@ by pointing Cookiecutter to its [GitHub repository][hypermodern python cookiecut
 Use the `--checkout` option with the [current stable release][2023.2.24]:
 
 ```console
-$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python --checkout="2023.2.24"
+$ cruft create https://github.com/statisticsnorway/ssb-pypitemplate.git --checkout=2023.2.24
 ```
 
-Cookiecutter downloads the template,
+Cruft downloads the template,
 and asks you a series of questions about project variables,
 for example, how you wish your project to be named.
 When you have answered these questions,
@@ -237,35 +237,38 @@ Here is a complete list of the project variables defined by this template:
   - Description
   - Example
 - - `project_name`
-  - Project name on PyPI and GitHub
-  - `hypermodern-python`
+  - Project name on PyPI and GitHub repo name
+  - `ssb-library`
 - - `package_name`
   - Import name of the package
-  - `hypermodern_python`
+  - `ssb_library`
 - - `friendly_name`
   - Friendly project name
-  - `Hypermodern Python`
+  - `SSB Library`
+- - `copyright_owner`
+  - Copyright owner
+  - Statistics Norway
+- - `copyright_year`
+  - The project copyright year
+  - `2023`
 - - `author`
-  - Primary author
-  - Katherine Johnson
+  - Name of the contact person
+  - Ola Nordmann
 - - `email`
-  - E-mail address of the author
-  - [email protected]
+  - E-mail address of the contact person
+  - [email protected]
 - - `github_organization`
   - GitHub organization or GitHub username of the author
-  - `katherine`
+  - `statisticsnorway`
 - - `version`
   - Initial project version
   - `0.0.0`
-- - `copyright_year`
-  - The project copyright year
-  - `2023`
 - - `license`
   - The project license
   - `MIT`
 - - `development_status`
   - Development status of the project
-  - `Development Status :: 3 - Alpha`
+  - `Development Status :: 4 - Beta`
 
 :::
 
@@ -279,7 +282,7 @@ Your choices are recorded in the file `.cookiecutter.json` in the generated proj
 together with the URL of this Cookiecutter template.
 Having this [JSON] file in the project makes it possible later on
 to update your project with changes from the Cookiecutter template,
-using tools such as [cupper].
+using tools such as [cruft].
 
 In the remainder of this guide,
 `<project>` and `<package>` are used
@@ -2613,7 +2616,7 @@ You can also read the articles on [this blog][hypermodern python blog].
 [cookiecutter]: https://github.com/cookiecutter/cookiecutter
 [coverage.py]: https://coverage.readthedocs.io/
 [crazy-max/ghaction-github-labeler]: https://github.com/crazy-max/ghaction-github-labeler
-[cupper]: https://github.com/senseyeio/cupper
+[cruft]: https://cruft.github.io/cruft/
 [curl]: https://curl.se
 [cyclomatic complexity]: https://en.wikipedia.org/wiki/Cyclomatic_complexity
 [darglint codes]: https://github.com/terrencepreilly/darglint#error-codes

docs/quickstart.md

@@ -40,6 +40,9 @@ Generate a Python project:
 cruft create https://github.com/statisticsnorway/ssb-pypitemplate.git --checkout=2023.2.24
 ```
 
+Cruft downloads the template and asks you a series of questions about project variables.
+Further details can be found in the [Creating a project] section of the user guide.
+
 Change to the root directory of your new project,
 and create a Git repository:
 
@@ -54,17 +57,10 @@ $ git commit
 Run the command-line interface from the source tree:
 
 ```console
-$ poetry install
+$ poetry update
 $ poetry run <project>
 ```
 
-Run an interactive Python session:
-
-```console
-$ poetry install
-$ poetry run python
-```
-
 ## Testing
 
 Run the full test suite:
@@ -104,6 +100,7 @@ $ nox -s pre-commit -- install
    - Owner: GitHub organization name or GitHub username that owns the repository.
    - Repository name: Name of the GitHub repo.
    - Workflow name: `release.yml`
+   - Environment: Leave empty.
 
 ### TestPyPI
 
@@ -116,11 +113,7 @@ $ nox -s pre-commit -- install
    - Owner: GitHub organization name or GitHub username that owns the repository.
    - Repository name: Name of the GitHub repo.
    - Workflow name: `release.yml`
-
-### Codecov
-
-1. Sign up at [Codecov].
-2. Install their GitHub app.
+   - Environment: Leave empty.
 
 ### GitHub Pages
 
@@ -184,8 +177,8 @@ by applying labels to them, like this:
 
 <!-- table-release-drafter-sections-end -->
 
-[codecov]: https://about.codecov.io/
 [cookiecutter]: https://github.com/cookiecutter/cookiecutter
+[creating a project]: https://statisticsnorway.github.io/ssb-pypitemplate/guide.html#creating-a-project
 [cruft]: https://cruft.github.io/cruft/
 [github]: https://github.com/
 [github pages]: https://docs.github.com/en/pages

{{cookiecutter.project_name}}/.github/labels.yml

@@ -10,9 +10,6 @@
 - name: bug
   description: Something isn't working
   color: d73a4a
-- name: build
-  description: Build System and Dependencies
-  color: bfdadc
 - name: ci
   description: Continuous Integration
   color: 4a97d6
@@ -64,3 +61,6 @@
 - name: wontfix
   description: This will not be worked on
   color: ffffff
+- name: "skip-changelog"
+  description: Changes that should be omitted from the release notes
+  color: ededed

{{cookiecutter.project_name}}/.github/release-drafter.yml

@@ -22,7 +22,8 @@ categories:
   - title: ":package: Dependencies"
     labels:
       - "dependencies"
-      - "build"
+exclude-labels:
+  - "skip-changelog"
 template: |
   ## Changes
 

{{cookiecutter.project_name}}/.github/workflows/constraints.txt

@@ -1,5 +1,5 @@
 pip==23.2.1
 nox==2023.4.22
 nox-poetry==1.0.3
-poetry==1.5.1
-virtualenv==20.24.2
+poetry==1.6.1
+virtualenv==20.24.4

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

@@ -1,4 +1,4 @@
-name: DeployDocs
+name: Documentation
 
 on:
   push:

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

@@ -20,6 +20,6 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Run Labeler
-        uses: crazy-max/ghaction-github-labeler@v4.1.0
+        uses: crazy-max/ghaction-github-labeler@v4.2.0
         with:
           skip-delete: true

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

@@ -67,7 +67,7 @@ jobs:
         if: "! steps.check-version.outputs.tag"
         uses: pypa/[email protected]
         with:
-          repository_url: https://test.pypi.org/legacy/
+          repository-url: https://test.pypi.org/legacy/
 
       - name: Publish the release notes
         uses: release-drafter/[email protected]

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

@@ -149,8 +149,10 @@ jobs:
         run: |
           nox --session=coverage -- xml
 
-      - name: Upload coverage report
-        uses: codecov/[email protected]
+      # Need to fix coverage source paths for SonarCloud scanning in GitHub actions.
+      # Replace root path with /github/workspace (mounted in docker container).
+      - name: Override coverage source paths for SonarCloud
+        run: sed -i "s/<source>\/home\/runner\/work\/{{cookiecutter.project_name}}\/{{cookiecutter.project_name}}/<source>\/github\/workspace/g" coverage.xml
 
       - name: SonarCloud Scan
         env: