From b1a55e692f2fdb691b1acefccbe5e3f58061959f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arne=20S=C3=B8rli?= <81353974+arneso-ssb@users.noreply.github.com> Date: Mon, 28 Aug 2023 10:36:16 +0200 Subject: [PATCH] Documentation updates - Fix missing formatting with black - Fix release date - Replace some cjolowicz links with statisticsnorway --- .pre-commit-config.yaml | 2 +- docs/changes.md | 15 +++++++++++---- docs/guide.md | 10 +++++----- docs/index.md | 4 ++-- docs/quickstart.md | 18 ++++++++++++++++-- .../.pre-commit-config.yaml | 4 ++-- {{cookiecutter.project_name}}/noxfile.py | 12 ++++++++++-- 7 files changed, 47 insertions(+), 18 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 69fe74dbe..6f24db179 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -8,6 +8,6 @@ repos: - id: trailing-whitespace - id: check-added-large-files - repo: https://github.com/pre-commit/mirrors-prettier - rev: v3.0.1 + rev: v3.0.2 hooks: - id: prettier diff --git a/docs/changes.md b/docs/changes.md index a46870bda..0710db6ba 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -5,16 +5,23 @@ to the hypermodern python cookiecutter are described on this page. - Use [cruft] instead of [cookiecutter] to create instances of the template. _Cruft supports updating instances when the template is updated._ -- Adopt template for use in Statistics Norway. - - _Template variables updated to support github_organization and copyright_owner._ - - _Replace all references to cjolowicz-repos with ssb-pypitemplate._ +- Adopt template for use in Statistics Norway: + - Template variables updated to support github_organization and copyright_owner. + - Replace all references to cjolowicz-repos with ssb-pypitemplate. +- Replace use of [Read the Docs] with [GitHub Pages]. _One site less to register to._ +- Add [SonarCloud] as a code quality analysis tool, including code coverage. +- Remove use of [CodeCov]. _One site less to register to and covered by SonarCloud._ - Support running `pytest` directly from the command line, without using `nox`. - Add library function example. _The original template only had a command line tool example._ -- Document generation works out of the box. +- Document generation works out of the box, even without `nox`. _Use `make html` in the docs directory._ - Fix warnings in GitHub Actions. +[codecov]: https://about.codecov.io/ [cookiecutter]: https://github.com/cookiecutter/cookiecutter [cruft]: https://cruft.github.io/cruft/ +[github pages]: https://docs.github.com/en/pages [hypermodern python cookiecutter]: https://github.com/cjolowicz/cookiecutter-hypermodern-python +[read the docs]: https://readthedocs.org/ +[sonarcloud]: https://www.sonarsource.com/products/sonarcloud/ diff --git a/docs/guide.md b/docs/guide.md index 0618c3458..5ad93db87 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -59,7 +59,7 @@ Here is a detailed list of features for this Python template: The {{ HPC }} uses [Calendar Versioning] with a `YYYY.MM.DD` versioning scheme. -The current stable release is [2022.6.3]. +The current stable release is [2023.2.24]. (installation)= @@ -212,10 +212,10 @@ $ poetry self update Create a project from this template by pointing Cookiecutter to its [GitHub repository][hypermodern python cookiecutter]. -Use the `--checkout` option with the [current stable release][2022.6.3]: +Use the `--checkout` option with the [current stable release][2023.2.24]: ```console -$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python --checkout="2022.6.3" +$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python --checkout="2023.2.24" ``` Cookiecutter downloads the template, @@ -257,7 +257,7 @@ Here is a complete list of the project variables defined by this template: - `0.0.0` - - `copyright_year` - The project copyright year - - `2022` + - `2023` - - `license` - The project license - `MIT` @@ -2581,7 +2581,7 @@ You can also read the articles on [this blog][hypermodern python blog]. [.github/dependabot.yml]: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file [.gitignore]: https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring [.readthedocs.yml]: https://docs.readthedocs.io/en/stable/config-file/v2.html -[2022.6.3]: https://github.com/cjolowicz/cookiecutter-hypermodern-python/releases/tag/2022.6.3 +[2023.2.24]: https://github.com/cjolowicz/cookiecutter-hypermodern-python/releases/tag/2023.2.24 [__main__]: https://docs.python.org/3/library/__main__.html [abstract syntax tree]: https://docs.python.org/3/library/ast.html [actions/cache]: https://github.com/actions/cache diff --git a/docs/index.md b/docs/index.md index a65babc5e..5b98e230a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ contributing Code of Conduct license Major changes -Changelog +Changelog ``` ```{include} ../README.md @@ -28,7 +28,7 @@ based on the [Hypermodern Python] article series. ## Usage ```console -$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python --checkout="2022.6.3" +cruft create https://github.com/statisticsnorway/ssb-pypitemplate.git --checkout=2023.2.24 ``` ## Features diff --git a/docs/quickstart.md b/docs/quickstart.md index 803e7d48f..8b49a9a31 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -37,7 +37,7 @@ It is recommended to set up Python 3.8, 3.9, 3.10 and 3.11 using [pyenv]. Generate a Python project: ```console -$ cruft create https://github.com/statisticsnorway/ssb-pypitemplate.git +cruft create https://github.com/statisticsnorway/ssb-pypitemplate.git --checkout=2023.2.24 ``` Change to the root directory of your new project, @@ -128,10 +128,23 @@ $ nox -s pre-commit -- install 2. Select Settings, Pages and set Source to "GitHub Actions" below the Build and Deployment heading. -[GitHub Pages] should work out of the box. The pages are deployed to
+[GitHub Pages] should then work out of the box. The pages are deployed to
`.github.io/` or
`.github.io/`. +### SonarCloud + +1. Log in to [SonarCloud] with your GitHub account. +2. Click the plus-sign at upper right and select _Analyze new project_, + select your organization and the new repo to analyze, and then click + the _Set Up_ button. +3. Set _new code_ to be based on _Number of days_ and 60 days (suggestion). + And then click the _Create project_ button. +4. Choose Analysis Method: _With GitHub Actions_. +5. Follow the description to add a GitHub repository secret for the `SONAR_TOKEN`. +6. That's it. The next time code are pushed to a branch or merged to main on GitHub, + the code will be analysed by SonarCloud. + ## Releasing Releases are triggered by a version bump on the default branch. @@ -185,5 +198,6 @@ by applying labels to them, like this: [pyenv]: https://github.com/pyenv/pyenv [pypi]: https://pypi.org/ [read the docs]: https://readthedocs.org/ +[sonarcloud]: https://www.sonarsource.com/products/sonarcloud/ [testpypi]: https://test.pypi.org/ [trusted publisher]: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/ diff --git a/{{cookiecutter.project_name}}/.pre-commit-config.yaml b/{{cookiecutter.project_name}}/.pre-commit-config.yaml index db89560ef..2acca9094 100644 --- a/{{cookiecutter.project_name}}/.pre-commit-config.yaml +++ b/{{cookiecutter.project_name}}/.pre-commit-config.yaml @@ -12,7 +12,7 @@ repos: name: black entry: black language: system - types: [python, jupyter] + types_or: [python, jupyter] require_serial: true - id: check-added-large-files name: Check for added large files @@ -73,6 +73,6 @@ repos: types: [text] stages: [commit, push, manual] - repo: https://github.com/pre-commit/mirrors-prettier - rev: v3.0.1 + rev: v3.0.2 hooks: - id: prettier diff --git a/{{cookiecutter.project_name}}/noxfile.py b/{{cookiecutter.project_name}}/noxfile.py index 16083c960..12d929d23 100644 --- a/{{cookiecutter.project_name}}/noxfile.py +++ b/{{cookiecutter.project_name}}/noxfile.py @@ -171,8 +171,16 @@ def tests(session: Session) -> None: session.install(".") session.install("coverage[toml]", "pytest", "pygments") try: - session.run("coverage", "run", "--parallel", "-m", "pytest", "-o", - "pythonpath=", *session.posargs) + session.run( + "coverage", + "run", + "--parallel", + "-m", + "pytest", + "-o", + "pythonpath=", + *session.posargs, + ) finally: if session.interactive: session.notify("coverage", posargs=[])