From dd868cce4d65c0bd22d84cb59606d3a83e50b391 Mon Sep 17 00:00:00 2001
From: Alexander Hess <alexander@webartifex.biz>
Date: Tue, 10 Sep 2024 03:22:52 +0200
Subject: [PATCH] Run `poetry publish` on GitHub actions

---
 .github/workflows/release.yml | 33 +++++++++++++++++++++++++++++++++
 README.md                     | 18 +++++++++++++++++-
 docs/index.rst                | 16 ++++++++++++++++
 3 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/release.yml

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..37db62a
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,33 @@
+name: release
+on:
+  release:
+    types: [published]
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    name: release-to-pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          # Make all of the below versions available simultaneously
+          python-version: |
+            3.9
+            3.10
+            3.11
+            3.12
+          architecture: x64
+
+      - run: python --version
+      - run: pip --version
+
+      # The following pinned dependencies must be updated manually
+      - run: pip install nox==2024.4.15
+      - run: pip install poetry==1.8.3
+
+      # Run some CI tasks before to ensure code/docs are still good;
+      # the "test" session is run once for every Pyhthon version above
+      - run: nox -s audit docs lint test test-docstrings
+
+      - run: poetry build
+      - run: poetry publish --username=__token__ --password=${{ secrets.PYPI_TOKEN }}
diff --git a/README.md b/README.md
index ad173c5..3f6e39c 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,10 @@ The goal of the `lalib` project is to create
     by reading and writing code.
 
 
+[![PyPI: Package version](https://img.shields.io/pypi/v/lalib?color=blue)](https://pypi.org/project/lalib/)
+[![PyPI: Supported Python versions](https://img.shields.io/pypi/pyversions/lalib)](https://pypi.org/project/lalib/)
+[![PyPI: Number of monthly downloads](https://img.shields.io/pypi/dm/lalib)](https://pypistats.org/packages/lalib)
+
 [![Documentation: Status](https://readthedocs.org/projects/lalib/badge/?version=latest)](https://lalib.readthedocs.io/en/latest/?badge=latest)
 [![Test suite: Status](https://github.com/webartifex/lalib/actions/workflows/tests.yml/badge.svg)](https://github.com/webartifex/lalib/actions/workflows/tests.yml)
 [![Test coverage: codecov](https://codecov.io/github/webartifex/lalib/graph/badge.svg?token=J4LWOMVP0R)](https://codecov.io/github/webartifex/lalib)
@@ -16,6 +20,18 @@ The goal of the `lalib` project is to create
 [![Code linting: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
 
+## Installation
+
+This project is published on [PyPI](https://pypi.org/project/lalib/).
+To install it, open any Python prompt and type:
+
+`pip install lalib`
+
+You may want to do so
+    within a [virtual environment](https://docs.python.org/3/library/venv.html)
+    or a [Jupyter notebook](https://docs.jupyter.org/en/latest/#what-is-a-notebook).
+
+
 ## Contributing & Development
 
 This project is open for any kind of contribution,
@@ -136,7 +152,7 @@ This ensures that past branches remain visible in the logs,
 The version identifiers adhere to a subset of the rules in
     [PEP440](https://peps.python.org/pep-0440/) and
     follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-So, releases to [PyPI](https://pypi.org/)
+So, releases to [PyPI](https://pypi.org/project/lalib/#history)
     come in the popular `major.minor.patch` format.
 The specific rules for this project are explained
     [here](https://github.com/webartifex/lalib/blob/main/tests/test_version.py).
diff --git a/docs/index.rst b/docs/index.rst
index 465f50f..fc8e1bc 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -21,5 +21,21 @@ Python 3.9 or newer is needed.
 The package depends only on core Python (incl. the standard library).
 
 
+Installation
+------------
+
+`lalib`_ is available on `PyPI`_ via `pip`_:
+
+.. code-block:: console
+
+   $ pip install lalib
+
+It is recommended to install the package into a `virtual environment`_.
+
+
 .. _standard library: https://docs.python.org/3/library/index.html
+.. _lalib: https://github.com/webartifex/lalib
+.. _pip: https://pip.pypa.io/en/stable/
+.. _pypi: https://pypi.org/
 .. _python: https://docs.python.org/3/
+.. _virtual environment: https://docs.python.org/3/tutorial/venv.html