Skip to content

Commit a9e3d63

Browse files
llucaxllucax
authored
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
2 parents 2f38f34 + 0003ad2 commit a9e3d63

36 files changed

+732
-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: 111 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,6 @@ jobs:
1717
steps:
1818
- name: Fetch sources
1919
uses: actions/checkout@v3
20-
with:
21-
submodules: true
2220

2321
- name: Set up Python
2422
uses: actions/setup-python@v4
@@ -46,8 +44,6 @@ jobs:
4644
steps:
4745
- name: Fetch sources
4846
uses: actions/checkout@v3
49-
with:
50-
submodules: true
5147

5248
- name: Set up Python
5349
uses: actions/setup-python@v4
@@ -69,8 +65,118 @@ jobs:
6965
path: dist/
7066
if-no-files-found: error
7167

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