Generate and publish API docs (#72)

The documentation is generated using MkDocs, using the Material theme
plus mkdocstrings (and a few minor supporting extensions) to build the
API documentation extracted from code comments.

Author: llucax

.github/labeler.yml

@@ -21,6 +21,7 @@
 
 "part:docs": 
   - "**/*.md"
+  - "docs/**"
   - LICENSE
 
 "part:microgrid":
@@ -33,12 +34,16 @@
   - "tests/**"
 
 "part:tooling":
+  - "**/*.ini"
+  - "**/*.toml"
+  - "**/*.yaml"
+  - "**/*.yml"
+  - "*requirements*.txt"
   - ".git*"
   - ".git*/**"
-  - "**/*.toml"
-  - "**/*.ini"
   - CODEOWNERS
   - MANIFEST.in
-  - "*requirements*.txt"
+  - docs/mkdocstrings_autoapi.py
+  - noxfile.py
   - setup.cfg
   - setup.py

.github/workflows/ci.yaml

@@ -66,8 +66,118 @@ jobs:
           path: dist/
           if-no-files-found: error
 
-  create-github-release:
+  generate-docs-pr:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Fetch sources
+        uses: actions/checkout@v3
+
+      - name: Setup Git user and e-mail
+        uses: frequenz-floss/setup-git-user@v1
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install .[docs]
+
+      - name: Generate the documentation
+        env:
+          MIKE_VERSION: pr-${{ github.event.number }}
+        run: |
+          mike deploy $MIKE_VERSION
+          mike set-default $MIKE_VERSION
+
+      - name: Upload site
+        uses: actions/upload-artifact@v3
+        with:
+          name: frequenz-channels-python-site
+          path: site/
+          if-no-files-found: error
+
+  publish-docs:
     needs: ["test", "build-dist"]
+    if: github.event_name == 'push'
+    runs-on: ubuntu-20.04
+    permissions:
+      contents: write
+    steps:
+      - name: Calculate and check version
+        id: mike-metadata
+        env:
+          REF: ${{ github.ref }}
+          REF_NAME: ${{ github.ref_name }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          aliases=
+          version=
+          if test "$REF_NAME" = "$DEFAULT_BRANCH"
+          then
+            version=next
+          # A tag that starts with vX.Y or X.Y
+          elif echo "$REF" | grep -q '^refs/tags' && echo "$REF_NAME" | grep -Pq '^v?\d+\.\d+\.'
+          then
+            if echo "$REF_NAME" | grep -Pq -- "-" # pre-release
+            then
+              echo "::notice title=Documentation was not published::" \
+                "The tag '$REF_NAME' looks like a pre-release."
+              exit 0
+            fi
+            version=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+\.[0-9]+)\..*$/\1/') # vX.Y
+            major=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
+            default_major=$(echo "$DEFAULT_BRANCH" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
+            aliases=$major
+            if test "$major" = "$default_major"
+            then
+              aliases="$aliases latest"
+            fi
+          else
+            echo "::warning title=Documentation was not published::" \
+              "Don't know how to handle '$REF' to make 'mike' version."
+            exit 0
+          fi
+          echo "version=$version" >> $GITHUB_OUTPUT
+          echo "aliases=$aliases" >> $GITHUB_OUTPUT
+
+      - name: Fetch sources
+        if: steps.mike-metadata.outputs.version
+        uses: actions/checkout@v3
+
+      - name: Setup Git user and e-mail
+        if: steps.mike-metadata.outputs.version
+        uses: frequenz-floss/setup-git-user@v1
+
+      - name: Set up Python
+        if: steps.mike-metadata.outputs.version
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+
+      - name: Install build dependencies
+        if: steps.mike-metadata.outputs.version
+        run: |
+          python -m pip install -U pip
+          python -m pip install .[docs]
+
+      - name: Fetch the gh-pages branch
+        if: steps.mike-metadata.outputs.version
+        run: git fetch origin gh-pages --depth=1
+
+      - name: Publish site
+        if: steps.mike-metadata.outputs.version
+        env:
+          VERSION: ${{ steps.mike-metadata.outputs.version }}
+          ALIASES: ${{ steps.mike-metadata.outputs.aliases }}
+        run: |
+          mike deploy --push --update-aliases "$VERSION" $ALIASES
+
+  create-github-release:
+    needs: ["publish-docs"]
     # Create a release only on tags creation
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
     permissions:

.gitignore

@@ -140,3 +140,7 @@ cython_debug/
 
 # PyCharm
 .idea
+
+# Automatically generated documentation
+docs/reference/
+site/

CONTRIBUTING.md

@@ -41,6 +41,58 @@ python -m pip install pytest pytest-asyncio
 pytest tests/test_sdk.py
 ```
 
+To build the documentation, first install the dependencies:
+
+```sh
+python -m pip install -e .[docs]
+```
+
+Then you can build the documentation (it will be written in the `site/`
+directory):
+
+```sh
+mkdocs build
+```
+
+Or you can just serve the documentation without building it using:
+
+```sh
+mkdocs serve
+```
+
+Your site will be updated **live** when you change your files (provided that
+you used `pip install -e .`, beware of a common pitfall of using `pip install`
+without `-e`, in that case the API reference won't change unless you do a new
+`pip install`).
+
+To build multi-version documentation, we use
+[mike](https://github.com/jimporter/mike). If you want to see how the
+multi-version sites looks like locally, you can use:
+
+```sh
+mike deploy my-version
+mike set-default my-version
+mike serve
+```
+
+`mike` works in mysterious ways. Some basic information:
+
+* `mike deploy` will do a `mike build` and write the results to your **local**
+  `gh-pages` branch. `my-version` is an arbitrary name for the local version
+  you want to preview.
+* `mike set-default` is needed so when you serve the documentation, it goes to
+  your newly produced documentation by default.
+* `mike serve` will serve the contents of your **local** `gh-pages` branch. Be
+  aware that, unlike `mkdocs serve`, changes to the sources won't be shown
+  live, as the `mike deploy` step is needed to refresh them.
+
+Be careful not to use `--push` with `mike deploy`, otherwise it will push your
+local `gh-pages` branch to the `origin` remote.
+
+That said, if you want to test the actual website in **your fork**, you can
+always use `mike deploy --push --remote your-fork-remote`, and then access the
+GitHub pages produced for your fork.
+
 ## Releasing
 
 These are the steps to create a new release:

README.md

@@ -1,5 +1,9 @@
 # Frequenz Python SDK
 
+[<img alt="GitHub Workflow Status" src="https://img.shields.io/github/workflow/status/frequenz-floss/frequenz-sdk-python/frequenz-sdk-python">](https://github.com/frequenz-floss/frequenz-sdk-python/actions/workflows/ci.yaml)
+[<img alt="PyPI" src="https://img.shields.io/pypi/v/frequenz-sdk">](https://pypi.org/project/frequenz-sdk/)
+[<img alt="PyPI" src="https://img.shields.io/badge/docs-latest-informational">](https://frequenz-floss.github.io/frequenz-sdk-python/)
+
 A development kit to interact with the Frequenz development platform.
 
 ## Supported Python versions
@@ -10,5 +14,4 @@ A development kit to interact with the Frequenz development platform.
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please
-check out the [Contributing
-Guide](https://github.com/frequenz-floss/frequenz-sdk-python/CONTRIBUTING.md).
+check out the [Contributing Guide](CONTRIBUTING.md).

RELEASE_NOTES.md

@@ -2,7 +2,12 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+The project has a new home!
+
+https://frequenz-floss.github.io/frequenz-sdk-python/
+
+For now the documentation is pretty scarce but we will be improving it with
+time.
 
 ## Upgrading
 

benchmarks/data_ingestion/benchmark_microgrid_data.py

@@ -1,11 +1,7 @@
-"""Benchmark for microgrid data.
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
-Copyright
-Copyright © 2022 Frequenz Energy-as-a-Service GmbH
-
-License
-MIT
-"""
+"""Benchmark for microgrid data."""
 
 import asyncio
 import time

benchmarks/power_distribution/power_distributor.py

@@ -1,11 +1,7 @@
-"""Check how long it takes to distribute power.
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
-Copyright
-Copyright © 2022 Frequenz Energy-as-a-Service GmbH
-
-License
-MIT
-"""
+"""Check how long it takes to distribute power."""
 
 import asyncio
 import csv

docs/CONTRIBUTING.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

docs/SUMMARY.md

@@ -0,0 +1,3 @@
+* [Home](index.md)
+* [API Reference](reference/)
+* [Development](CONTRIBUTING.md)