Backport documentation generation to v0.10.x (#35)

See #25 for details. - ci/labeler: Add missing noxfile.py - Use MkDocs to build the documentation - Move copyright and license as code comments - docs: Add missing file format to examples - docs: Add some useful cross-references. - docs: Indent examples - Use forward type annotations - docs: Indent "Returns:" properly - docs: Improve formatting of some symbols - docs: Make some minor improvements - docs: Add site version via mike - ci: Remove unnecessary checkout of submodules - ci: Build and publish documentation - Run normal linting on noxfile.py - Run mypy on noxfile.py and be more restrictive - ci: Add contents permission to publish-docs
frequenz-floss · Nov 4, 2022 · a9e3d63 · a9e3d63
2 parents 2f38f34 + 0003ad2
commit a9e3d63
Show file tree

Hide file tree

Showing 36 changed files with 732 additions and 368 deletions.
diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -8,19 +8,23 @@
 
 "part:docs": 
   - "**/*.md"
+  - "docs/**"
   - LICENSE
 
 "part:tests":
   - "tests/**"
 
 "part:tooling":
+  - "**/*.ini"
+  - "**/*.toml"
+  - "**/*.yaml"
+  - "*requirements*.txt"
   - ".git*"
   - ".git*/**"
-  - "**/*.toml"
-  - "**/*.ini"
   - CODEOWNERS
   - MANIFEST.in
-  - "*requirements*.txt"
+  - docs/mkdocstrings_autoapi.py
+  - noxfile.py
   - setup.py
 
 "part:channels":

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -17,8 +17,6 @@ jobs:
     steps:
     - name: Fetch sources
       uses: actions/checkout@v3
-      with:
-        submodules: true
 
     - name: Set up Python
       uses: actions/setup-python@v4
@@ -46,8 +44,6 @@ jobs:
     steps:
       - name: Fetch sources
         uses: actions/checkout@v3
-        with:
-          submodules: true
 
       - name: Set up Python
         uses: actions/setup-python@v4
@@ -69,8 +65,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: "3.10"
+
+      - 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: "3.10"
+
+      - 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 "$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:

diff --git a/.gitignore b/.gitignore
@@ -127,3 +127,7 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# Automatically generated documentation
+docs/reference/
+site/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -29,6 +29,58 @@ python -m pip install nox
 nox
 ```
 
+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
 =========
 

diff --git a/benchmarks/benchmark_anycast.py b/benchmarks/benchmark_anycast.py
@@ -1,11 +1,7 @@
-"""Benchmark for Anycast channels.
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
-Copyright
-Copyright © 2022 Frequenz Energy-as-a-Service GmbH
-
-License
-MIT
-"""
+"""Benchmark for Anycast channels."""
 
 import asyncio
 import csv

diff --git a/benchmarks/benchmark_broadcast.py b/benchmarks/benchmark_broadcast.py
@@ -1,11 +1,7 @@
-"""Benchmark for Broadcast channels.
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
-Copyright
-Copyright © 2022 Frequenz Energy-as-a-Service GmbH
-
-License
-MIT
-"""
+"""Benchmark for Broadcast channels."""
 
 import asyncio
 import csv

diff --git a/docs/css/mkdocstrings.css b/docs/css/mkdocstrings.css
@@ -0,0 +1,44 @@
+/* Recommended style from:
+ * https://mkdocstrings.github.io/python/customization/#recommended-style-material
+ * With some additions from:
+ * https://github.com/mkdocstrings/mkdocstrings/blob/master/docs/css/mkdocstrings.css
+ */
+
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: 4px solid rgba(230, 230, 230);
+  margin-bottom: 80px;
+}
+
+/* Avoid breaking parameters name, etc. in table cells. */
+td code {
+  word-break: normal !important;
+}
+
+/* Mark external links as such. */
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="rgb(0, 0, 0)" d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  position: relative;
+  top: 0.1em;
+  margin-left: 0.2em;
+  margin-right: 0.1em;
+
+  height: 1em;
+  width: 1em;
+  border-radius: 100%;
+  background-color: var(--md-typeset-a-color);
+}
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}
diff --git a/docs/css/style.css b/docs/css/style.css
@@ -0,0 +1,28 @@
+/* Based on:
+ * https://github.com/mkdocstrings/mkdocstrings/blob/master/docs/css/style.css
+ */
+
+/* Increase logo size */
+.md-header__button.md-logo {
+    padding-bottom: 0.2rem;
+    padding-right: 0;
+}
+.md-header__button.md-logo img {
+    height: 1.5rem;
+}
+
+/* Mark external links as such (also in nav) */
+a.external:hover::after, a.md-nav__link[href^="https:"]:hover::after {
+  /* https://primer.style/octicons/link-external-16 */
+  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill="rgb(233, 235, 252)" d="M10.604 1h4.146a.25.25 0 01.25.25v4.146a.25.25 0 01-.427.177L13.03 4.03 9.28 7.78a.75.75 0 01-1.06-1.06l3.75-3.75-1.543-1.543A.25.25 0 0110.604 1zM3.75 2A1.75 1.75 0 002 3.75v8.5c0 .966.784 1.75 1.75 1.75h8.5A1.75 1.75 0 0014 12.25v-3.5a.75.75 0 00-1.5 0v3.5a.25.25 0 01-.25.25h-8.5a.25.25 0 01-.25-.25v-8.5a.25.25 0 01.25-.25h3.5a.75.75 0 000-1.5h-3.5z"></path></svg>');
+  height: 0.8em;
+  width: 0.8em;
+  margin-left: 0.2em;
+  content: ' ';
+  display: inline-block;
+}
+
+/* More space at the bottom of the page */
+.md-main__inner {
+  margin-bottom: 1.5rem;
+}
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,5 @@
+# Home
+
+Welcome to Frequenz's channels implementation for Python.
+
+This website is still under heavy construction. Most information can be found in the [Reference](reference/frequenz/channels) section.
diff --git a/docs/logo.png b/docs/logo.png
diff --git a/docs/mkdocstrings_autoapi.py b/docs/mkdocstrings_autoapi.py
@@ -0,0 +1,40 @@
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
+
+"""Generate the code reference pages.
+
+Based on the recipe at:
+https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+SRC_PATH = "src"
+DST_PATH = "reference"
+
+# type ignore because mkdocs_gen_files uses a very weird module-level
+# __getattr__() which messes up the type system
+nav = mkdocs_gen_files.Nav()  # type: ignore
+
+for path in sorted(Path(SRC_PATH).rglob("*.py")):
+    module_path = path.relative_to(SRC_PATH).with_suffix("")
+
+    doc_path = path.relative_to(SRC_PATH).with_suffix(".md")
+    full_doc_path = Path(DST_PATH, doc_path)
+    parts = tuple(module_path.parts)
+    if parts[-1] == "__init__":
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+        parts = parts[:-1]
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        fd.write(f"::: {'.'.join(parts)}\n")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, Path("..") / path)
+
+with mkdocs_gen_files.open(Path(DST_PATH) / "SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest (stable) version.
+  <a href="{{ '../' ~ base_url }}"> 
+    <strong>Click here to go to latest (stable) version</strong>
+  </a>
+{% endblock %}