Use MkDocs to build the documentation

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.

For now the home page is a place holder, and the supporting script
`docs/mkdocstrings-autoapi.py` should eventually be moved to a common
repository.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

.github/labeler.yml

@@ -8,6 +8,7 @@
 
 "part:docs": 
   - "**/*.md"
+  - "docs/**"
   - LICENSE
 
 "part:tests":
@@ -16,11 +17,13 @@
 "part:tooling":
   - "**/*.ini"
   - "**/*.toml"
+  - "**/*.yaml"
   - "*requirements*.txt"
   - ".git*"
   - ".git*/**"
   - CODEOWNERS
   - MANIFEST.in
+  - docs/mkdocstrings_autoapi.py
   - noxfile.py
   - setup.py
 

.gitignore

@@ -127,3 +127,7 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# Automatically generated documentation
+docs/reference/
+site/

CONTRIBUTING.md

@@ -29,6 +29,25 @@ 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
+```
+
 Releasing
 =========
 

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);
+}

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;
+}

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.

docs/logo.png

@@ -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"
+
+# noqa because mkdocs_gen_files uses a very weird module-level
+# __getattr__() which messes up the type system
+nav = mkdocs_gen_files.Nav()  # noqa
+
+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())

docs/mkdocstrings_autoapi.py

@@ -0,0 +1,99 @@
+# MkDocs configuration
+# For details see: https://www.mkdocs.org/user-guide/configuration/
+
+# Project information
+site_name: Frequenz's channels for Python
+site_description: Frequenz's channels implementation for Python.
+site_author: Frequenz Energy-as-a-Service GmbH
+copyright: Frequenz Energy-as-a-Service GmbH
+repo_name: "frequenz-channels-python"
+repo_url: "https://github.com/frequenz-floss/frequenz-channels-python"
+edit_uri: "edit/v0.x.x/docs/"
+
+# Build directories
+theme:
+  name: "material"
+  logo: logo.png
+  favicon: logo.png
+  language: en
+  icon:
+    edit: material/file-edit-outline
+    repo: fontawesome/brands/github
+  features:
+    - navigation.instant
+    - navigation.tabs
+    - navigation.top
+    - navigation.tracking
+    - toc.follow
+  palette:
+  - media: "(prefers-color-scheme: light)"
+    scheme: default
+    primary: indigo
+    accent: deep purple
+    toggle:
+      icon: material/weather-sunny
+      name: Switch to dark mode
+  - media: "(prefers-color-scheme: dark)"
+    scheme: slate
+    primary: black
+    accent: teal
+    toggle:
+      icon: material/weather-night
+      name: Switch to light mode
+
+extra:
+  social:
+  - icon: fontawesome/brands/github
+    link: https://github.com/frequenz-floss
+  - icon: fontawesome/brands/linkedin
+    link: https://www.linkedin.com/company/frequenz-com
+
+extra_css:
+  - css/style.css
+  - css/mkdocstrings.css
+
+# Formatting options
+markdown_extensions:
+  - admonition
+  - attr_list
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tasklist
+  - pymdownx.tabbed
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: "!!python/name:pymdownx.superfences.fence_code_format"
+  - toc:
+      permalink: "¤"
+
+plugins:
+  - gen-files:
+      scripts:
+        - docs/mkdocstrings_autoapi.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - mkdocstrings:
+      custom_templates: templates
+      default_handler: python
+      handlers:
+        python:
+          options:
+            paths: [src]
+            docstring_section_style: spacy
+            merge_init_into_class: false
+            show_category_heading: true
+            show_root_heading: true
+            show_root_members_full_path: true
+            show_source: true
+          import:
+            - https://docs.python.org/3/objects.inv
+  - search
+  - section-index
+
+# Preview controls
+watch:
+  - src

mkdocs.yml

@@ -9,18 +9,24 @@
 
 import nox
 
+check_dirs = [
+        "benchmarks",
+        "docs",
+        "src",
+        "tests",
+        ]
 
 @nox.session
 def formatting(session: nox.Session) -> None:
     session.install("black", "isort")
-    session.run("black", "--check", "src", "tests", "benchmarks")
-    session.run("isort", "--check", "src", "tests", "benchmarks")
+    session.run("black", "--check", *check_dirs)
+    session.run("isort", "--check", *check_dirs)
 
 
 @nox.session
 def pylint(session: nox.Session) -> None:
-    session.install(".", "pylint", "pytest")
-    session.run("pylint", "src", "tests", "benchmarks")
+    session.install(".[docs]", "pylint", "pytest")
+    session.run("pylint", *check_dirs)
 
 
 @nox.session
@@ -35,9 +41,7 @@ def mypy(session: nox.Session) -> None:
         "--explicit-package-bases",
         "--follow-imports=silent",
         "--strict",
-        "src",
-        "tests",
-        "benchmarks",
+        *check_dirs,
     )
 
 
@@ -46,7 +50,7 @@ def docstrings(session: nox.Session) -> None:
     """Check docstring tone with pydocstyle and param descriptions with darglint."""
     session.install("pydocstyle", "darglint", "toml")
 
-    session.run("pydocstyle", "src", "tests", "benchmarks")
+    session.run("pydocstyle", *check_dirs)
 
     # Darglint checks that function argument and return values are documented.
     # This is needed only for the `src` dir, so we exclude the other top level