Skip to content

Commit a49fa3e

Browse files
llucaxllucax
authored
Use MkDocs to build the documentation (#25)
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.
2 parents 2385ea0 + 3e3e771 commit a49fa3e

36 files changed

+730
-368
lines changed

‎.github/labeler.yml‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,19 +8,23 @@
88

99
"part:docs":
1010
- "**/*.md"
11+
- "docs/**"
1112
- LICENSE
1213

1314
"part:tests":
1415
- "tests/**"
1516

1617
"part:tooling":
18+
- "**/*.ini"
19+
- "**/*.toml"
20+
- "**/*.yaml"
21+
- "*requirements*.txt"
1722
- ".git*"
1823
- ".git*/**"
19-
- "**/*.toml"
20-
- "**/*.ini"
2124
- CODEOWNERS
2225
- MANIFEST.in
23-
- "*requirements*.txt"
26+
- docs/mkdocstrings_autoapi.py
27+
- noxfile.py
2428
- setup.py
2529

2630
"part:channels":

‎.github/workflows/ci.yaml‎

Lines changed: 109 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,6 @@ jobs:
1818
steps:
1919
- name: Fetch sources
2020
uses: actions/checkout@v3
21-
with:
22-
submodules: true
2321

2422
- name: Set up Python
2523
uses: actions/setup-python@v4
@@ -47,8 +45,6 @@ jobs:
4745
steps:
4846
- name: Fetch sources
4947
uses: actions/checkout@v3
50-
with:
51-
submodules: true
5248

5349
- name: Set up Python
5450
uses: actions/setup-python@v4
@@ -70,8 +66,116 @@ jobs:
7066
path: dist/
7167
if-no-files-found: error
7268

73-
create-github-release:
69+
generate-docs-pr:
70+
if: github.event_name == 'pull_request'
71+
runs-on: ubuntu-20.04
72+
steps:
73+
- name: Fetch sources
74+
uses: actions/checkout@v3
75+
76+
- name: Setup Git user and e-mail
77+
uses: frequenz-floss/setup-git-user@v1
78+
79+
- name: Set up Python
80+
uses: actions/setup-python@v4
81+
with:
82+
python-version: "3.10"
83+
84+
- name: Install build dependencies
85+
run: |
86+
python -m pip install -U pip
87+
python -m pip install .[docs]
88+
89+
- name: Generate the documentation
90+
env:
91+
MIKE_VERSION: pr-${{ github.event.number }}
92+
run: |
93+
mike deploy $MIKE_VERSION
94+
mike set-default $MIKE_VERSION
95+
96+
- name: Upload site
97+
uses: actions/upload-artifact@v3
98+
with:
99+
name: frequenz-channels-python-site
100+
path: site/
101+
if-no-files-found: error
102+
103+
publish-docs:
74104
needs: ["test", "build-dist"]
105+
if: github.event_name == 'push'
106+
runs-on: ubuntu-20.04
107+
steps:
108+
- name: Calculate and check version
109+
id: mike-metadata
110+
env:
111+
REF: ${{ github.ref }}
112+
REF_NAME: ${{ github.ref_name }}
113+
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
114+
run: |
115+
aliases=
116+
version=
117+
if test "$REF_NAME" = "$DEFAULT_BRANCH"
118+
then
119+
version=next
120+
# A tag that starts with vX.Y or X.Y
121+
elif echo "$REF" | grep -q '^refs/tags' && echo "$REF_NAME" | grep -Pq '^v?\d+\.\d+\.'
122+
then
123+
if echo "$REF_NAME" | grep -Pq -- "-" # pre-release
124+
then
125+
echo "::notice title=Documentation was not published::" \
126+
"The tag '$REF_NAME' looks like a pre-release."
127+
exit 0
128+
fi
129+
version=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+\.[0-9]+)\..*$/\1/') # vX.Y
130+
major=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
131+
default_major=$(echo "$DEFAULT_BRANCH" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
132+
aliases=$major
133+
if test "$major" = "$default_major"
134+
then
135+
aliases="$aliases latest"
136+
fi
137+
else
138+
echo "::warning title=Documentation was not published::" \
139+
"Don't know how to handle '$REF' to make 'mike' version."
140+
exit 0
141+
fi
142+
echo "version=$version" >> $GITHUB_OUTPUT
143+
echo "aliases=$aliases" >> $GITHUB_OUTPUT
144+
145+
- name: Fetch sources
146+
if: steps.mike-metadata.outputs.version
147+
uses: actions/checkout@v3
148+
149+
- name: Setup Git user and e-mail
150+
if: steps.mike-metadata.outputs.version
151+
uses: frequenz-floss/setup-git-user@v1
152+
153+
- name: Set up Python
154+
if: steps.mike-metadata.outputs.version
155+
uses: actions/setup-python@v4
156+
with:
157+
python-version: "3.10"
158+
159+
- name: Install build dependencies
160+
if: steps.mike-metadata.outputs.version
161+
run: |
162+
python -m pip install -U pip
163+
python -m pip install .[docs]
164+
165+
- name: Fetch the gh-pages branch
166+
if: steps.mike-metadata.outputs.version
167+
run: git fetch origin gh-pages --depth=1
168+
169+
- name: Publish site
170+
if: steps.mike-metadata.outputs.version
171+
env:
172+
VERSION: ${{ steps.mike-metadata.outputs.version }}
173+
ALIASES: ${{ steps.mike-metadata.outputs.aliases }}
174+
run: |
175+
mike deploy --push "$VERSION" $ALIASES
176+
177+
create-github-release:
178+
needs: ["publish-docs"]
75179
# Create a release only on tags creation
76180
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
77181
permissions:

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,3 +127,7 @@ dmypy.json
127127

128128
# Pyre type checker
129129
.pyre/
130+
131+
# Automatically generated documentation
132+
docs/reference/
133+
site/

‎CONTRIBUTING.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,58 @@ python -m pip install nox
2929
nox
3030
```
3131

32+
To build the documentation, first install the dependencies:
33+
34+
```sh
35+
python -m pip install -e .[docs]
36+
```
37+
38+
Then you can build the documentation (it will be written in the `site/`
39+
directory):
40+
41+
```sh
42+
mkdocs build
43+
```
44+
45+
Or you can just serve the documentation without building it using:
46+
47+
```sh
48+
mkdocs serve
49+
```
50+
51+
Your site will be updated **live** when you change your files (provided that
52+
you used `pip install -e .`, beware of a common pitfall of using `pip install`
53+
without `-e`, in that case the API reference won't change unless you do a new
54+
`pip install`).
55+
56+
To build multi-version documentation, we use
57+
[mike](https://github.com/jimporter/mike). If you want to see how the
58+
multi-version sites looks like locally, you can use:
59+
60+
```sh
61+
mike deploy my-version
62+
mike set-default my-version
63+
mike serve
64+
```
65+
66+
`mike` works in mysterious ways. Some basic information:
67+
68+
* `mike deploy` will do a `mike build` and write the results to your **local**
69+
`gh-pages` branch. `my-version` is an arbitrary name for the local version
70+
you want to preview.
71+
* `mike set-default` is needed so when you serve the documentation, it goes to
72+
your newly produced documentation by default.
73+
* `mike serve` will serve the contents of your **local** `gh-pages` branch. Be
74+
aware that, unlike `mkdocs serve`, changes to the sources won't be shown
75+
live, as the `mike deploy` step is needed to refresh them.
76+
77+
Be careful not to use `--push` with `mike deploy`, otherwise it will push your
78+
local `gh-pages` branch to the `origin` remote.
79+
80+
That said, if you want to test the actual website in **your fork**, you can
81+
always use `mike deploy --push --remote your-fork-remote`, and then access the
82+
GitHub pages produced for your fork.
83+
3284
Releasing
3385
=========
3486

‎benchmarks/benchmark_anycast.py‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
1-
"""Benchmark for Anycast channels.
1+
# License: MIT
2+
# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
23

3-
Copyright
4-
Copyright © 2022 Frequenz Energy-as-a-Service GmbH
5-
6-
License
7-
MIT
8-
"""
4+
"""Benchmark for Anycast channels."""
95

106
import asyncio
117
import csv

‎benchmarks/benchmark_broadcast.py‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
1-
"""Benchmark for Broadcast channels.
1+
# License: MIT
2+
# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
23

3-
Copyright
4-
Copyright © 2022 Frequenz Energy-as-a-Service GmbH
5-
6-
License
7-
MIT
8-
"""
4+
"""Benchmark for Broadcast channels."""
95

106
import asyncio
117
import csv

‎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: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Home
2+
3+
Welcome to Frequenz's channels implementation for Python.
4+
5+
This website is still under heavy construction. Most information can be found in the [Reference](reference/frequenz/channels) section.

‎docs/logo.png‎

55.9 KB
Loading

0 commit comments

Comments
 (0)