build: Add setup script and adapt docs workflow to poetry

.github/workflows/docs.yml

@@ -2,7 +2,7 @@ name: docs
 
 on:
   push:
-    branches: [main]
+    branches: [main, poetry-and-rename]
     paths:
       - "docs/**"
       - README.md
@@ -24,20 +24,23 @@ jobs:
         uses: actions/checkout@v3
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v4 # Uses the Python version in the .python-version file
+      - name: Install Poetry
+        uses: snok/install-poetry@v1 # Uses settings from poetry.toml
         with:
-          python-version: "3.11"
+          version: "1.4.2"
+          installer-parallel: true
       - name: Load cached dependencies
+        id: cache
         uses: actions/cache@v3
         with:
-          path: ~/.cache/pip
-          key: docs-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/pyproject.toml') }}
+          path: .venv
+          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('poetry.lock') }}
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install .[docs]
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: scripts/setup
       - name: Build documentation
-        run: scripts/docs --no-reload
+        run: poetry run sphinx-build -b html docs docs/_build
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         if: github.ref == 'refs/heads/main'

poetry.toml

@@ -0,0 +1,3 @@
+[virtualenvs]
+create = true
+in-project = true

pyproject.toml

@@ -3,8 +3,7 @@ name = "aiomqtt-test"
 version = "0.0.0"  # Placeholder: Managed by poetry-dynamic-versioning
 description = "The idiomatic asyncio MQTT client, wrapped around paho-mqtt"
 license = "BSD-3-Clause"
-authors = ["Frederik Aalund <fpa@sbtinstruments.com>"]
-maintainers = ["Felix Böhm <felix@felixboehm.dev>", "Jonathan Plasse <jonathan.plasse@live.fr>"]
+authors = ["Frederik Aalund <fpa@sbtinstruments.com>", "Felix Böhm <felix@felixboehm.dev>", "Jonathan Plasse <jonathan.plasse@live.fr>"]
 readme = "README.md"
 packages = [{include = "asyncio_mqtt"}]
 repository = "https://github.com/sbtinstruments/asyncio-mqtt"
@@ -20,9 +19,9 @@ classifiers = [
 "Issue tracker" = "https://github.com/sbtinstruments/asyncio-mqtt/issues"
 
 [tool.poetry.dependencies]
-python = "^3.8"
+python = "^3.7"
 paho-mqtt = ">=1.6.0"
-typing-extensions = {version = ">=4.4.0", markers = "python_version < \"3.10\""}
+typing-extensions = {version = ">=4.4.0", markers = "python_version < '3.10'"}
 
 [tool.poetry.group.dev]
 optional = true
@@ -35,16 +34,16 @@ black = "^23.3.0"
 pytest = "^7.3.1"
 pytest-cov = "^4.0.0"
 anyio = "^3.6.2"
-sphinx = "^6.2.1"
 furo = "^2023.3.27"
 sphinx-autobuild = "^2021.3.14"
 myst-parser = "^1.0.0"
 sphinx-copybutton = "^0.5.2"
+sphinx = "^5.3"
 
 [tool.poetry-dynamic-versioning]
 enable = true
 vcs = "git"
-style = "semver"
+style = "pep440"
 strict = true
 metadata = false
 

scripts/docs

@@ -5,35 +5,5 @@ set -o errexit -o pipefail -o nounset
 # Change into the project's directory
 cd "$(dirname "$0")/.."
 
-# Positional argument array
-POSITIONALS=()
-# Define our default argument values
-RELOAD=1
-
-# Extract options and their arguments into variables
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        -n|--no-reload)
-            RELOAD=0
-            shift
-            ;;
-        -*|--*)
-            echo "Unknown option $1" >&2
-            exit 1
-            ;;
-        *)
-            POSITIONALS+=("$1")
-            shift
-            ;;
-    esac
-done
-
-# Restore positional arguments
-if [ ${#POSITIONALS[@]} -gt 0 ]; then set -- "${POSITIONALS[@]}"; fi
-
-# Main script
-if [[ $RELOAD -eq 1 ]]; then
-    sphinx-autobuild --port 8145 docs docs/_build
-else
-    sphinx-build -b html docs docs/_build
-fi
+# Serve the documentation
+poetry run sphinx-autobuild --port 8145 --open-browser docs docs/_build

scripts/setup

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+# Safety first
+set -o errexit -o pipefail -o nounset
+# Change into the project's directory
+cd "$(dirname "$0")/.."
+
+# Install the dependencies
+poetry install --with dev