Publish doc to GitHub Pages

- Update documentation - Fix links and badges
statisticsnorway · Aug 29, 2023 · ed78305 · ed78305
1 parent 6ed4035
commit ed78305
Show file tree

Hide file tree

Showing 8 changed files with 66 additions and 26 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,14 +1,25 @@
-name: Check documentation
-on: [push, pull_request]
+name: Documentation
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch: # Allows you to run this workflow manually from the Actions tab
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 jobs:
-  docs:
+  build:
     name: Build documentation & check links
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4.5.0
+      - uses: actions/setup-python@v4.7.0
         with:
-          python-version: "3.8"
+          python-version: "3.11"
       - run: |
           pip install --constraint=.github/workflows/constraints.txt pip
           pip install --constraint=.github/workflows/constraints.txt nox
@@ -20,3 +31,23 @@ jobs:
           path: docs/_build
       - name: Check links
         run: nox --force-color --session=linkcheck
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Setup Pages
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        uses: actions/configure-pages@v3
+
+      - name: Deploy to GitHub Pages
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        id: deployment
+        uses: actions/deploy-pages@v2
diff --git a/README.md b/README.md
@@ -17,21 +17,21 @@
 [black project]: https://github.com/psf/black
 [calver badge]: https://img.shields.io/badge/calver-YYYY.MM.DD-22bfda.svg
 [calver]: https://calver.org/
-[code of conduct]: https://github.com/cjolowicz/cookiecutter-hypermodern-python/blob/main/CODE_OF_CONDUCT.md
+[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
 [contributor covenant badge]: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
-[github actions badge]: https://github.com/cjolowicz/cookiecutter-hypermodern-python/workflows/Tests/badge.svg
-[github actions page]: https://github.com/cjolowicz/cookiecutter-hypermodern-python/actions?workflow=Tests
-[github page]: https://github.com/cjolowicz/cookiecutter-hypermodern-python
-[license badge]: https://img.shields.io/github/license/cjolowicz/cookiecutter-hypermodern-python
+[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
+[github page]: https://github.com/statisticsnorway/ssb-pypitemplate
+[license badge]: https://img.shields.io/github/license/statisticsnorway/ssb-pypitemplate
 [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/
-[status badge]: https://badgen.net/badge/status/alpha/d8624d
+[status badge]: https://badgen.net/badge/status/beta/d8624d
 
 <!-- badges-end -->
 
@@ -89,7 +89,7 @@ cruft update
 - Generate command-line reference with [sphinx-click]
 - Manage project labels with [GitHub Labeler]
 
-The template supports Python 3.8, 3.9, 3.10 and 3.11.
+The template supports Python 3.9, 3.10 and 3.11.
 
 [autodoc]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
 [bandit]: https://github.com/PyCQA/bandit

diff --git a/docs/conf.py b/docs/conf.py
@@ -2,8 +2,8 @@
 from datetime import datetime
 
 
-project = "Hypermodern Python Cookiecutter"
-author = "Claudio Jolowicz"
+project = "SSB PyPI Template"
+author = "Claudio Jolowicz and Statistics Norway"
 copyright = f"{datetime.now().year}, {author}"
 extensions = ["sphinx.ext.intersphinx", "myst_parser"]
 intersphinx_mapping = {"mypy": ("https://mypy.readthedocs.io/en/stable/", None)}

diff --git a/docs/guide.md b/docs/guide.md
@@ -7,8 +7,10 @@ myst:
 # User Guide
 
 This is the user guide
-for the [Hypermodern Python Cookiecutter],
+for the [SSB PyPI Template],
 a Python template based on the [Hypermodern Python] article series.
+It is a fork of [Hypermodern Python Cookiecutter] and adopted for use in
+[Statistics Norway].
 
 If you're in a hurry, check out the [quickstart guide](quickstart)
 and the [tutorials](tutorials).
@@ -2729,13 +2731,15 @@ You can also read the articles on [this blog][hypermodern python blog].
 [safety]: https://github.com/pyupio/safety
 [salsify/action-detect-and-tag-new-version]: https://github.com/salsify/action-detect-and-tag-new-version
 [schlawack semantic]: https://hynek.me/articles/semver-will-not-save-you/
-[schreiner constraints]: https://iscinumpy.dev/post/bound-version-constraints/
-[schreiner poetry]: https://iscinumpy.dev/post/poetry-versions/
+[schreiner constraints]: https://iscinumpy.gitlab.io/post/bound-version-constraints/
+[schreiner poetry]: https://iscinumpy.gitlab.io/post/poetry-versions/
 [semantic versioning]: https://semver.org/
 [sphinx configuration]: https://www.sphinx-doc.org/en/master/usage/configuration.html
 [sphinx-autobuild]: https://github.com/executablebooks/sphinx-autobuild
 [sphinx-click]: https://sphinx-click.readthedocs.io/
 [sphinx]: http://www.sphinx-doc.org/
+[ssb pypi template]: https://github.com/statisticsnorway/ssb-pypitemplate
+[statistics norway]: https://www.ssb.no/
 [test fixture]: https://docs.pytest.org/en/latest/explanation/fixtures.html#about-fixtures
 [testpypi]: https://test.pypi.org/
 [toml]: https://github.com/toml-lang/toml

diff --git a/docs/index.md b/docs/index.md
@@ -1,4 +1,4 @@
-# Hypermodern Python Cookiecutter
+# SSB PyPI Template
 
 ```{toctree}
 ---
@@ -23,12 +23,20 @@ end-before: <!-- badges-end -->
 ```
 
 [Cookiecutter] template for a Python package
-based on the [Hypermodern Python] article series.
+based on the [Hypermodern Python] article series,
+and adopted for use in [Statistics Norway].
 
 ## Usage
 
+Use [Cruft](https://cruft.github.io/cruft/) to create and update an instance of this template.
+
 ```console
 cruft create https://github.com/statisticsnorway/ssb-pypitemplate.git --checkout=2023.2.24
+
+# 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:
+cruft check
+cruft update
 ```
 
 ## Features
@@ -81,3 +89,4 @@ All images on the
 [hypermodern python]: https://medium.com/@cjolowicz/hypermodern-python-d44485d9d769
 [hypermodernism]: https://en.wikipedia.org/wiki/Hypermodernism_(chess)
 [retrofuturism]: https://en.wikipedia.org/wiki/Retrofuturism
+[statistics norway]: https://www.ssb.no/
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -30,7 +30,7 @@ $ pipx inject nox nox-poetry
 
 [pipx] is preferred, but you can also install with `pip install --user`.
 
-It is recommended to set up Python 3.8, 3.9, 3.10 and 3.11 using [pyenv].
+It is recommended to set up Python 3.9, 3.10 and 3.11 using [pyenv].
 
 ## Creating a project
 

diff --git a/{{cookiecutter.project_name}}/.github/workflows/docs.yml b/{{cookiecutter.project_name}}/.github/workflows/docs.yml
@@ -9,12 +9,6 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:

diff --git a/{{cookiecutter.project_name}}/README.md b/{{cookiecutter.project_name}}/README.md
@@ -11,13 +11,15 @@
 
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
 [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)][poetry]
 
 [pypi status]: https://pypi.org/project/{{cookiecutter.project_name}}/
 [read the docs]: https://{{cookiecutter.project_name}}.readthedocs.io/
 [tests]: https://github.com/{{cookiecutter.github_organization}}/{{cookiecutter.project_name}}/actions?workflow=Tests
 [codecov]: https://app.codecov.io/gh/{{cookiecutter.github_organization}}/{{cookiecutter.project_name}}
 [pre-commit]: https://github.com/pre-commit/pre-commit
 [black]: https://github.com/psf/black
+[poetry]: https://python-poetry.org/
 
 ## Features