Skip to content

Commit 4ff31e1

Browse files
MarenzMarenz
authored
Improve mike versions (#150)
This pull request introduces a significant changes to the versioning scheme for `mike`. This change aims to provide greater clarity and organization to our version management and implement correct sorting. - `next` becomes `v0.x-dev`: This alias now aligns with our development branch. - Pre-releases receive their own versioning: For example, `v0.7-pre` is introduced for pre-release versions. - `latest` points to the latest stable version. - New aliases are added for the latest pre-release (`latest-pre`) and the development branch (`latest-dev`). They ensure that users can easily identify and access the documentation version they require, whether it's a stable release, pre-release, or the latest development build. The versions now also provide more descriptive title, using the full tag name for tags and adding a short commit hash for development versions, so users can know exactly which version they are reading the documentation for. Fixes #149, fixes #135, fixes #76.
2 parents 2c5b0e0 + 73931c8 commit 4ff31e1

File tree

35 files changed

+2038
-363
lines changed

35 files changed

+2038
-363
lines changed

‎.github/workflows/ci.yaml‎

Lines changed: 29 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -311,78 +311,60 @@ jobs:
311311
permissions:
312312
contents: write
313313
steps:
314-
- name: Calculate and check version
315-
id: mike-metadata
316-
env:
317-
REF: ${{ github.ref }}
318-
REF_NAME: ${{ github.ref_name }}
319-
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
320-
run: |
321-
aliases=
322-
version=
323-
if test "$REF_NAME" = "$DEFAULT_BRANCH"
324-
then
325-
version=next
326-
# A tag that starts with vX.Y or X.Y
327-
elif echo "$REF" | grep -q '^refs/tags' && echo "$REF_NAME" | grep -Pq '^v?\d+\.\d+\.'
328-
then
329-
if echo "$REF_NAME" | grep -Pq -- "-" # pre-release
330-
then
331-
echo "::notice title=Documentation was not published::" \
332-
"The tag '$REF_NAME' looks like a pre-release."
333-
exit 0
334-
fi
335-
version=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+\.[0-9]+)\..*$/\1/') # vX.Y
336-
major=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
337-
default_major=$(echo "$DEFAULT_BRANCH" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
338-
aliases=$major
339-
if test "$major" = "$default_major"
340-
then
341-
aliases="$aliases latest"
342-
fi
343-
else
344-
echo "::warning title=Documentation was not published::" \
345-
"Don't know how to handle '$REF' to make 'mike' version."
346-
exit 0
347-
fi
348-
echo "version=$version" >> $GITHUB_OUTPUT
349-
echo "aliases=$aliases" >> $GITHUB_OUTPUT
350-
351314
- name: Fetch sources
352-
if: steps.mike-metadata.outputs.version
353315
uses: actions/checkout@v4
354316
with:
355317
submodules: true
356318

357319
- name: Setup Git user and e-mail
358-
if: steps.mike-metadata.outputs.version
359320
uses: frequenz-floss/setup-git-user@v2
360321

361322
- name: Set up Python
362-
if: steps.mike-metadata.outputs.version
363323
uses: actions/setup-python@v4
364324
with:
365325
python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
366326
cache: 'pip'
367327

368328
- name: Install build dependencies
369-
if: steps.mike-metadata.outputs.version
370329
run: |
371330
python -m pip install -U pip
372331
python -m pip install .[dev-mkdocs]
373332
pip freeze
374333
334+
- name: Calculate and check version
335+
id: mike-version
336+
env:
337+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
338+
GITHUB_REPO: ${{ github.repository }}
339+
GIT_REF: ${{ github.ref }}
340+
GIT_SHA: ${{ github.sha }}
341+
run: |
342+
python -m frequenz.repo.config.cli.version.mike.info
343+
375344
- name: Fetch the gh-pages branch
376-
if: steps.mike-metadata.outputs.version
345+
if: steps.mike-version.outputs.version
377346
run: git fetch origin gh-pages --depth=1
378347

379-
- name: Publish site
380-
if: steps.mike-metadata.outputs.version
348+
- name: Build site
349+
if: steps.mike-version.outputs.version
381350
env:
382-
VERSION: ${{ steps.mike-metadata.outputs.version }}
383-
ALIASES: ${{ steps.mike-metadata.outputs.aliases }}
351+
VERSION: ${{ steps.mike-version.outputs.version }}
352+
TITLE: ${{ steps.mike-version.outputs.title }}
353+
ALIASES: ${{ steps.mike-version.outputs.aliases }}
354+
run: |
355+
mike deploy --update-aliases --title "$TITLE" "$VERSION" $ALIASES
356+
357+
- name: Sort site versions
358+
if: steps.mike-version.outputs.version
359+
run: |
360+
git checkout gh-pages
361+
python -m frequenz.repo.config.cli.version.mike.sort versions.json
362+
git commit -a -m "Sort versions.json"
363+
364+
- name: Publish site
365+
if: steps.mike-version.outputs.version
384366
run: |
385-
mike deploy --push --update-aliases "$VERSION" $ALIASES
367+
git push origin gh-pages
386368
387369
create-github-release:
388370
name: Create GitHub release

‎RELEASE_NOTES.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,14 @@
2020
- `docs/overrides` -> `docs/_overrides`
2121
- `logo.png` -> `docs/_img/logo.png`
2222

23+
- You might need to remove old `mike` version aliases. Probably removing `next` should be enough:
24+
25+
```bash
26+
mike delete -p next
27+
```
28+
29+
You can use `mike list` to list all versions and aliases.
30+
2331
- CI
2432

2533
- You can now make your branch protection rule only require the "Test with nox" CI job to pass. All the matrix expansions will merge into it, so there is no need to change branch protection rules if matrix elements are added or removed.
@@ -43,6 +51,11 @@
4351
- Make code annotations numbered. This is useful to hint about the order one should read the annotations.
4452
- Add a navigation footer to show previous and next pages. This is specially useful when reading the documentation in a mobile device since the navigation bar is hidden.
4553
- Updated dependencies.
54+
- We use a new `mike` versioning scheme:
55+
56+
- Versions now have a title with the full tag name for tags and includes the (short) commit SHA for branches so users can know exactly which version they are reading.
57+
- Pre-releases are now published too as `vX.Y-pre`. They have aliases to point to the latest pre-release in a major (`vX-pre`) and the absolute latest pre-release (`latest-pre`).
58+
- All branches are now published with their own version as `vX.Y-dev`. They have aliases to point to the latest version in a major (`vX-dev`) and the absolute latest version (`latest-dev`). This means the old `next` becomes `latest-dev`.
4659

4760
- CI
4861

@@ -62,5 +75,6 @@
6275
- Fixed mermaid diagrams not rendering in the documentation.
6376
- `mypy` ignores for `cookiecutter` have been removed. They should have never be there as generated projects don't use `cookiecutter`.
6477
- `mypy` overrides now are applied to API projects too.
78+
- Now the `latest` `mike` version will point to the highest stable version available, not the latest version published.
6579
6680
- Dependabot branches are now not tested for `push` events, as they are already tested by `pull` events.

‎cookiecutter/hooks/post_gen_project.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ def main() -> None:
7575
print("mkdocs serve")
7676
print()
7777
print("To initialize the GitHub pages website:")
78-
print("mike deploy --update-aliases next latest")
78+
print("mike deploy --update-aliases v0.1-dev latest-dev latest")
7979
print("mike set-default latest")
8080
print("git push upstream gh-pages # or origin if you haven't forked the repo")
8181
print()

‎cookiecutter/{{cookiecutter.github_repo_name}}/.github/workflows/ci.yaml‎

Lines changed: 29 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -336,78 +336,60 @@ jobs:
336336
permissions:
337337
contents: write
338338
steps:
339-
- name: Calculate and check version
340-
id: mike-metadata
341-
env:
342-
REF: ${{ github.ref }}
343-
REF_NAME: ${{ github.ref_name }}
344-
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
345-
run: |
346-
aliases=
347-
version=
348-
if test "$REF_NAME" = "$DEFAULT_BRANCH"
349-
then
350-
version=next
351-
# A tag that starts with vX.Y or X.Y
352-
elif echo "$REF" | grep -q '^refs/tags' && echo "$REF_NAME" | grep -Pq '^v?\d+\.\d+\.'
353-
then
354-
if echo "$REF_NAME" | grep -Pq -- "-" # pre-release
355-
then
356-
echo "::notice title=Documentation was not published::" \
357-
"The tag '$REF_NAME' looks like a pre-release."
358-
exit 0
359-
fi
360-
version=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+\.[0-9]+)\..*$/\1/') # vX.Y
361-
major=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
362-
default_major=$(echo "$DEFAULT_BRANCH" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
363-
aliases=$major
364-
if test "$major" = "$default_major"
365-
then
366-
aliases="$aliases latest"
367-
fi
368-
else
369-
echo "::warning title=Documentation was not published::" \
370-
"Don't know how to handle '$REF' to make 'mike' version."
371-
exit 0
372-
fi
373-
echo "version=$version" >> $GITHUB_OUTPUT
374-
echo "aliases=$aliases" >> $GITHUB_OUTPUT
375-
376339
- name: Fetch sources
377-
if: steps.mike-metadata.outputs.version
378340
uses: actions/checkout@v4
379341
with:
380342
submodules: true
381343

382344
- name: Setup Git user and e-mail
383-
if: steps.mike-metadata.outputs.version
384345
uses: frequenz-floss/setup-git-user@v2
385346

386347
- name: Set up Python
387-
if: steps.mike-metadata.outputs.version
388348
uses: actions/setup-python@v4
389349
with:
390350
python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
391351
cache: 'pip'
392352

393353
- name: Install build dependencies
394-
if: steps.mike-metadata.outputs.version
395354
run: |
396355
python -m pip install -U pip
397356
python -m pip install .[dev-mkdocs]
398357
pip freeze
399358
359+
- name: Calculate and check version
360+
id: mike-version
361+
env:
362+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
363+
GITHUB_REPO: ${{ github.repository }}
364+
GIT_REF: ${{ github.ref }}
365+
GIT_SHA: ${{ github.sha }}
366+
run: |
367+
python -m frequenz.repo.config.cli.version.mike.info
368+
400369
- name: Fetch the gh-pages branch
401-
if: steps.mike-metadata.outputs.version
370+
if: steps.mike-version.outputs.version
402371
run: git fetch origin gh-pages --depth=1
403372

404-
- name: Publish site
405-
if: steps.mike-metadata.outputs.version
373+
- name: Build site
374+
if: steps.mike-version.outputs.version
406375
env:
407-
VERSION: ${{ steps.mike-metadata.outputs.version }}
408-
ALIASES: ${{ steps.mike-metadata.outputs.aliases }}
376+
VERSION: ${{ steps.mike-version.outputs.version }}
377+
TITLE: ${{ steps.mike-version.outputs.title }}
378+
ALIASES: ${{ steps.mike-version.outputs.aliases }}
379+
run: |
380+
mike deploy --update-aliases --title "$TITLE" "$VERSION" $ALIASES
381+
382+
- name: Sort site versions
383+
if: steps.mike-version.outputs.version
384+
run: |
385+
git checkout gh-pages
386+
python -m frequenz.repo.config.cli.version.mkdocs.sort versions.json
387+
git commit -a -m "Sort versions.json"
388+
389+
- name: Publish site
390+
if: steps.mike-version.outputs.version
409391
run: |
410-
mike deploy --push --update-aliases "$VERSION" $ALIASES
392+
git push origin gh-pages
411393
412394
create-github-release:
413395
name: Create GitHub release

‎cookiecutter/{{cookiecutter.github_repo_name}}/docs/_scripts/mkdocstrings_autoapi.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33

44
"""Generate the code reference pages."""
55

6-
from frequenz.repo.config import mkdocs
6+
from frequenz.repo.config.mkdocs import api_pages
77

8-
mkdocs.generate_python_api_pages("{{cookiecutter | src_path}}", "{{'python-' if cookiecutter.type == 'api'}}reference")
8+
api_pages.generate_python_api_pages("{{cookiecutter | src_path}}", "{{'python-' if cookiecutter.type == 'api'}}reference")
99
{%- if cookiecutter.type == 'api' %}
10-
mkdocs.generate_protobuf_api_pages()
10+
api_pages.generate_protobuf_api_pages()
1111
{%- endif %}

‎docs/_scripts/mkdocstrings_autoapi.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,6 @@
33

44
"""Generate the code reference pages."""
55

6-
from frequenz.repo.config import mkdocs
6+
from frequenz.repo.config.mkdocs import api_pages
77

8-
mkdocs.generate_python_api_pages("src", "reference")
8+
api_pages.generate_python_api_pages("src", "reference")

‎docs/index.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -182,11 +182,13 @@ initial setup is needed for it to work correctly:
182182

183183
```sh
184184
pip install -e .[dev-mkdocs] # Not necessary if you already installed .[dev]
185-
mike deploy --update-aliases next latest # Creates the branch gh-pages locally
185+
mike deploy --update-aliases v0.1-dev latest-dev latest # Creates the branch gh-pages locally
186186
mike set-default latest # Makes the latest alias the default version
187187
git push upstream gh-pages # Pushes the new branch upstream to publish the website
188188
```
189189

190+
This assumes your branch is called `v0.x.x` and your first release will be `v0.1.0`.
191+
190192
Then make sure that GitHub Pages is enabled in
191193
`https://github.com/<repo-owner>/<repo-name>/settings/pages`.
192194

@@ -199,9 +201,10 @@ The above commands create a new documentation version using
199201
[Mike](https://pypi.org/project/mike/), which is used to keep multiple versions
200202
of the website.
201203

202-
The new documentation version is called `next`, which is used as the name for
203-
the currently in-development branch. The `next` branch has an alias called
204-
`latest`, which is set as the *default*.
204+
The new documentation version is called `v0.1-dev`, which is used as the name for
205+
the currently in-development branch. The `v0.1-dev` branch has an alias called
206+
`latest-dev` that points to the latest in-development version, and `latest`
207+
alias, which is set as the *default*.
205208

206209
If the website is visited without specifying an explicit version, the `latest`
207210
version will be displayed. It is recommended to point `latest` to the latest
@@ -214,7 +217,8 @@ New versions of the documentation will be automatically generated and published
214217
via GitHub Actions on any push.
215218

216219
If a push is to a branch with semver-like format (vX.Y.Z), then the generated
217-
version will replace the current `next` version.
220+
version will replace the current `vX.Y-dev` version (and `vX-dev` and
221+
`latest-dev` alias).
218222

219223
If a tag is pushed instead, then the generated version will replace the current
220224
`vX.Y` version (if there was any), and the aliases `vX` and `latest` will be

‎pyproject.toml‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,12 @@ classifiers = [
3636
"Typing :: Typed",
3737
]
3838
requires-python = ">= 3.11, < 4"
39-
dependencies = ["nox >= 2022.11.21", "mkdocs-gen-files >= 0.4.0, < 0.6.0"]
39+
dependencies = [
40+
"nox >= 2022.11.21",
41+
"mkdocs-gen-files >= 0.4.0, < 0.6.0",
42+
"semver >= 3.0.1, < 4",
43+
"github-action-utils >= 1.1.0, < 2",
44+
]
4045
dynamic = ["version"]
4146

4247
[[project.authors]]
@@ -175,7 +180,9 @@ strict = true
175180
module = [
176181
"cookiecutter",
177182
"cookiecutter.*",
183+
"github_action_utils",
178184
"mkdocs_macros.*",
185+
"semver.version",
179186
"sybil",
180187
"sybil.*",
181188
]

‎src/frequenz/repo/config/__init__.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -234,9 +234,9 @@
234234
`mkdocs-gen-files` plugin as follows:
235235
236236
```python
237-
from frequenz.repo.config import mkdocs
237+
from frequenz.repo.config.mkdocs import api_pages
238238
239-
mkdocs.generate_python_api_pages("my_sources", "API")
239+
api_pages.generate_python_api_pages("my_sources", "API")
240240
```
241241
242242
Where `my_sources` is the directory containing the source files and `API` is the
@@ -359,10 +359,10 @@
359359
section:
360360
361361
```python
362-
from frequenz.repo.config import mkdocs
362+
from frequenz.repo.config.mkdocs import api_pages
363363
364-
mkdocs.generate_python_api_pages("my_sources", "API-py")
365-
mkdocs.generate_protobuf_api_pages()
364+
api_pages.generate_python_api_pages("my_sources", "API-py")
365+
api_pages.generate_protobuf_api_pages()
366366
```
367367
368368
This will use the configuration in the `pyproject.toml` file and requires `docker` to

‎src/frequenz/repo/config/cli/__init__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# License: MIT
2+
# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
3+
4+
"""Command line interface."""

0 commit comments

Comments
 (0)