Use MkDocs to build the documentation

llucax · llucax · commit 285ddd0b0866 · 2022-11-21T14:39:08.000+01:00
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 &lt;leandro.lucarella@frequenz.com&gt;
diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -21,6 +21,7 @@
 
 "part:docs": 
   - "**/*.md"
+  - "docs/**"
   - LICENSE
 
 "part:microgrid":
@@ -35,11 +36,14 @@
 "part:tooling":
   - "**/*.ini"
   - "**/*.toml"
+  - "**/*.yaml"
+  - "**/*.yml"
   - "*requirements*.txt"
   - ".git*"
   - ".git*/**"
   - CODEOWNERS
   - MANIFEST.in
+  - docs/mkdocstrings_autoapi.py
   - noxfile.py
   - setup.cfg
   - setup.py
diff --git a/.gitignore b/.gitignore
@@ -140,3 +140,7 @@ cython_debug/
 
 # PyCharm
 .idea
+
+# Automatically generated documentation
+docs/reference/
+site/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -41,6 +41,25 @@ 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
+```
+
 ## Releasing
 
 These are the steps to create a new release:
diff --git a/README.md b/README.md
@@ -10,5 +10,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).
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -0,0 +1,3 @@
+* [Home](index.md)
+* [API Reference](reference/)
+* [Development](CONTRIBUTING.md)
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 @@
+--8<-- "README.md"
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()
+
+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/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,101 @@
+# MkDocs configuration
+# For details see: https://www.mkdocs.org/user-guide/configuration/
+
+# Project information
+site_name: Frequenz Python SDK
+site_description: Frequenz Python SDK.
+site_author: Frequenz Energy-as-a-Service GmbH
+copyright: Frequenz Energy-as-a-Service GmbH
+repo_name: "frequenz-sdk-python"
+repo_url: "https://github.com/frequenz-floss/frequenz-sdk-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
+  - README.md
+  - CONTRIBUTING.md
diff --git a/noxfile.py b/noxfile.py
@@ -15,7 +15,13 @@ def source_file_paths(session: nox.Session) -> List[str]:
     not, we use all source files."""
     if session.posargs:
         return session.posargs
-    return ["src", "tests", "examples", "benchmarks"]
+    return [
+            "benchmarks",
+            "docs",
+            "examples",
+            "src",
+            "tests",
+            ]
 
 
 # Run all checks except `ci_checks` by default.  When running locally with just
@@ -38,7 +44,8 @@ def ci_checks_max(session: nox.Session) -> None:
 
     This does NOT run pytest_min, so that needs to be run separately as well.
     """
-    session.install(".", *PYTEST_DEPS, *FMT_DEPS, *LINT_DEPS, *DOCSTRING_DEPS)
+    session.install(".[docs]", *PYTEST_DEPS, *FMT_DEPS, *LINT_DEPS,
+            *DOCSTRING_DEPS)
 
     formatting(session, False)
     mypy(session, False)
@@ -101,7 +108,7 @@ def pylint(session: nox.Session, install_deps: bool = True) -> None:
     if install_deps:
         # install the package itself as editable, so that it is possible to do
         # fast local tests with `nox -R -e pylint`.
-        session.install("-e", ".", "pylint", *PYTEST_DEPS)
+        session.install("-e", ".[docs]", "pylint", *PYTEST_DEPS)
 
     paths = source_file_paths(session)
     session.run(
diff --git a/pyproject.toml b/pyproject.toml
@@ -47,6 +47,15 @@ dynamic = [ "version" ]
 name ="Frequenz Energy-as-a-Service GmbH"
 email = "floss@frequenz.com"
 
+[project.optional-dependencies]
+docs = [
+    "mkdocs-gen-files >= 0.4.0, < 0.5.0",
+    "mkdocs-literate-nav >= 0.4.0, < 0.5.0",
+    "mkdocs-material >= 8.5.7, < 9",
+    "mkdocs-section-index >= 0.3.4, < 0.4.0",
+    "mkdocstrings[python] >= 0.19.0, < 0.20.0",
+]
+
 [project.urls]
 Changelog = "https://github.com/frequenz-floss/frequenz-sdk-python/releases"
 Repository = "https://github.com/frequenz-floss/frequenz-sdk-python"

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+* [Home](index.md)`
	`2`	`+* [API Reference](reference/)`
	`3`	`+* [Development](CONTRIBUTING.md)`