Skip to content

Commit 0346a25

Browse files
llucaxstefan-brus-frequenz
llucax
authored and
stefan-brus-frequenz
committed
Add documentation generation using mkdocs
Signed-off-by: Leandro Lucarella <[email protected]>
1 parent fb8292a commit 0346a25

File tree

11 files changed

+230
-5
lines changed

11 files changed

+230
-5
lines changed

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,7 @@ py/frequenz/api/dispatch/**/*_pb2_grpc.pyi
99
.nox/*
1010
__pycache__
1111
.coverage
12+
13+
# Automatically generated documentation
14+
docs/reference/
15+
site/

‎docs/CONTRIBUTING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
--8<-- "CONTRIBUTING.md"

‎docs/SUMMARY.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
* [Home](index.md)
2+
* [Protobuf API Reference](protobuf-reference/)
3+
* [Python API Reference](python-reference/)
4+
* [Contributing](CONTRIBUTING.md)

‎docs/css/mkdocstrings.css‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
/* Recommended style from:
2+
* https://mkdocstrings.github.io/python/customization/#recommended-style-material
3+
* With some additions from:
4+
* https://github.com/mkdocstrings/mkdocstrings/blob/master/docs/css/mkdocstrings.css
5+
*/
6+
7+
/* Indentation. */
8+
div.doc-contents:not(.first) {
9+
padding-left: 25px;
10+
border-left: .05rem solid var(--md-typeset-table-color);
11+
}
12+
13+
/* Indentation. */
14+
div.doc-contents:not(.first) {
15+
padding-left: 25px;
16+
border-left: 4px solid rgba(230, 230, 230);
17+
margin-bottom: 80px;
18+
}
19+
20+
/* Avoid breaking parameters name, etc. in table cells. */
21+
td code {
22+
word-break: normal !important;
23+
}
24+
25+
/* Mark external links as such. */
26+
a.autorefs-external::after {
27+
/* https://primer.style/octicons/arrow-up-right-24 */
28+
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>');
29+
content: ' ';
30+
31+
display: inline-block;
32+
position: relative;
33+
top: 0.1em;
34+
margin-left: 0.2em;
35+
margin-right: 0.1em;
36+
37+
height: 1em;
38+
width: 1em;
39+
border-radius: 100%;
40+
background-color: var(--md-typeset-a-color);
41+
}
42+
a.autorefs-external:hover::after {
43+
background-color: var(--md-accent-fg-color);
44+
}

‎docs/css/style.css‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
/* Based on:
2+
* https://github.com/mkdocstrings/mkdocstrings/blob/master/docs/css/style.css
3+
*/
4+
5+
/* Increase logo size */
6+
.md-header__button.md-logo {
7+
padding-bottom: 0.2rem;
8+
padding-right: 0;
9+
}
10+
.md-header__button.md-logo img {
11+
height: 1.5rem;
12+
}
13+
14+
/* Mark external links as such (also in nav) */
15+
a.external:hover::after, a.md-nav__link[href^="https:"]:hover::after {
16+
/* https://primer.style/octicons/link-external-16 */
17+
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>');
18+
height: 0.8em;
19+
width: 0.8em;
20+
margin-left: 0.2em;
21+
content: ' ';
22+
display: inline-block;
23+
}
24+
25+
/* More space at the bottom of the page */
26+
.md-main__inner {
27+
margin-bottom: 1.5rem;
28+
}

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
--8<-- "README.md"

‎docs/logo.png‎

55.9 KB
Loading

‎docs/mkdocstrings_autoapi.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# License: MIT
2+
# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
3+
4+
"""Generate the code reference pages."""
5+
6+
from frequenz.repo.config import mkdocs
7+
8+
mkdocs.generate_python_api_pages("py", "python-reference")
9+
mkdocs.generate_protobuf_api_pages()

‎docs/overrides/main.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{% extends "base.html" %}
2+
3+
{% block outdated %}
4+
You're not viewing the latest (stable) version.
5+
<a href="{{ '../' ~ base_url }}">
6+
<strong>Click here to go to latest (stable) version</strong>
7+
</a>
8+
{% endblock %}

‎mkdocs.yml‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# MkDocs configuration
2+
# For details see: https://www.mkdocs.org/user-guide/configuration/
3+
4+
# Project information
5+
site_name: "Frequenz Dispatch API"
6+
site_description: "Frequenz gRPC API to propagate dispatches to microgrids"
7+
site_author: "Frequenz Energy-as-a-Service GmbH"
8+
copyright: "Copyright © 2023 Frequenz Energy-as-a-Service GmbH"
9+
repo_name: "frequenz-api-dispatch"
10+
repo_url: "https://github.com/frequenz-floss/frequenz-api-dispatch"
11+
edit_uri: "edit/v0.x.x/docs/"
12+
strict: true # Treat warnings as errors
13+
14+
# Build directories
15+
theme:
16+
name: "material"
17+
logo: logo.png
18+
favicon: logo.png
19+
language: en
20+
icon:
21+
edit: material/file-edit-outline
22+
repo: fontawesome/brands/github
23+
custom_dir: docs/overrides
24+
features:
25+
- content.code.annotate
26+
- content.code.copy
27+
- navigation.instant
28+
- navigation.tabs
29+
- navigation.top
30+
- navigation.tracking
31+
- toc.follow
32+
palette:
33+
- media: "(prefers-color-scheme: light)"
34+
scheme: default
35+
primary: indigo
36+
accent: deep purple
37+
toggle:
38+
icon: material/weather-sunny
39+
name: Switch to dark mode
40+
- media: "(prefers-color-scheme: dark)"
41+
scheme: slate
42+
primary: black
43+
accent: teal
44+
toggle:
45+
icon: material/weather-night
46+
name: Switch to light mode
47+
48+
extra:
49+
social:
50+
- icon: fontawesome/brands/github
51+
link: https://github.com/frequenz-floss
52+
- icon: fontawesome/brands/linkedin
53+
link: https://www.linkedin.com/company/frequenz-com
54+
version:
55+
provider: mike
56+
default: latest
57+
58+
extra_css:
59+
- css/style.css
60+
- css/mkdocstrings.css
61+
62+
# Formatting options
63+
markdown_extensions:
64+
- admonition
65+
- attr_list
66+
- pymdownx.details
67+
- pymdownx.highlight:
68+
anchor_linenums: true
69+
line_spans: __span
70+
pygments_lang_class: true
71+
- pymdownx.keys
72+
- pymdownx.snippets:
73+
check_paths: true
74+
- pymdownx.superfences:
75+
custom_fences:
76+
- name: mermaid
77+
class: mermaid
78+
format: "!!python/name:pymdownx.superfences.fence_code_format"
79+
- pymdownx.tabbed
80+
- pymdownx.tasklist
81+
- toc:
82+
permalink: "¤"
83+
84+
plugins:
85+
- gen-files:
86+
scripts:
87+
- docs/mkdocstrings_autoapi.py
88+
- literate-nav:
89+
nav_file: SUMMARY.md
90+
- mike:
91+
canonical_version: latest
92+
- mkdocstrings:
93+
custom_templates: templates
94+
default_handler: python
95+
handlers:
96+
python:
97+
options:
98+
paths: ["py"]
99+
docstring_section_style: spacy
100+
merge_init_into_class: false
101+
show_category_heading: true
102+
show_root_heading: true
103+
show_root_members_full_path: true
104+
show_source: true
105+
import:
106+
# See https://mkdocstrings.github.io/python/usage/#import for details
107+
- https://docs.python.org/3/objects.inv
108+
- https://grpc.github.io/grpc/python/objects.inv
109+
- https://typing-extensions.readthedocs.io/en/stable/objects.inv
110+
- search
111+
- section-index
112+
113+
# Preview controls
114+
watch:
115+
- "py"
116+
- README.md
117+
- CONTRIBUTING.md

0 commit comments

Comments
 (0)