From d632b4928abd9d025adfe828204869accdf13571 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 17:06:41 +0200 Subject: [PATCH] Publish doc to GitHub Pages - Update documentation - Fix links and badges --- .github/workflows/docs.yml | 41 ++++++++++++++++--- README.md | 14 +++---- docs/conf.py | 4 +- docs/guide.md | 10 +++-- docs/index.md | 13 +++++- docs/quickstart.md | 2 +- .../.github/workflows/docs.yml | 6 --- {{cookiecutter.project_name}}/README.md | 2 + 8 files changed, 66 insertions(+), 26 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 1c8bdd073..f72d0c1df 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,14 +1,27 @@ -name: Check documentation -on: [push, pull_request] +name: Documentation + +on: + push: + branches: + - main + - master + 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 +33,21 @@ 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 + uses: actions/configure-pages@v3 + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/README.md b/README.md index 6f8b7aa22..7ea435d4d 100644 --- 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 @@ -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 index 535647ef8..b67ac9580 100644 --- 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 index 5ad93db87..6e3c63e12 100644 --- 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 index 5b98e230a..d4c52dd40 100644 --- 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: ``` [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 index 8b49a9a31..3cbb091a6 100644 --- 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 index a01fb9fb4..dd387e83e 100644 --- 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 index c2ecaaac5..4af8997d6 100644 --- a/{{cookiecutter.project_name}}/README.md +++ b/{{cookiecutter.project_name}}/README.md @@ -11,6 +11,7 @@ [![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/ @@ -18,6 +19,7 @@ [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