Skip to content

Commit

Permalink
Add support and bump to mike 2.0.0 (#174)
Browse files Browse the repository at this point in the history
This PR upgrades `mike` to 2.0.0. This new version uses symlinks for
aliases by default, but they are not supported by GitHub Pages, so we
need to use the `redirect` alias type instead explicitly.

We use the new `alias_type` option in the `mike` plugin configuration in
the `mkdocs.yml` file to set the alias type to `redirect`.

It also avoid failing the documentation publishing job if the `mike`
version can't be determined (for example if the branch name is not
recognized). It will just emit a warning and skip the publishing.

Fixes #173.
  • Loading branch information
llucax authored Nov 6, 2023
2 parents 8bf6c38 + b9e2d84 commit 7e74141
Show file tree
Hide file tree
Showing 16 changed files with 64 additions and 13 deletions.
51 changes: 46 additions & 5 deletions RELEASE_NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,57 @@

## Summary

This release fixes a bug in `mike` version sorting.
This release upgrades `mike` to 2.0.0.

## Upgrading

- `frequenz.repo.config.mkdocs.mike.`: The `sort_versions()` function now takes plain `str`s as arguments instead of `MikeVersionInfo` objects.

### Cookiecutter template

There is no need to regenerate any templates with this release.
There is no need to re-generate the cookiecutter template for this release. Instead you can upgrade the `mike` package in your `pyproject.toml` file and add the new `alias_type: redirect` option to the `plugins.mike` key in the `mkdocs.yml` file.

You should be able to do this by running the following commands:

```sh
sed -i '/canonical_version: latest/ i\ alias_type: redirect' mkdocs.yml
sed -i 's/ "mike == .*",/ "mike == 2.0.0",/' pyproject.toml
```

Please make sure to check the diff and test if everything works as expected. After doing a `git diff` you should get something like:

```diff
diff --git a/mkdocs.yml b/mkdocs.yml
index 3d0f82e..6adfbe8 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -93,6 +93,7 @@ plugins:
- literate-nav:
nav_file: SUMMARY.md
- mike:
+ alias_type: redirect
canonical_version: latest
- mkdocstrings:
custom_templates: templates
diff --git a/pyproject.toml b/pyproject.toml
index 9a1604b..b183524 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -47,7 +47,7 @@ dev-formatting = ["black == 23.10.1", "isort == 5.12.0"]
dev-mkdocs = [
"black == 23.10.1",
"Markdown==3.5.1",
- "mike == 1.1.2",
+ "mike == 2.0.0",
"mkdocs-gen-files == 0.5.0",
"mkdocs-literate-nav == 0.6.1",
"mkdocs-material == 9.4.7",
```

If that's not the case, your `pyproject.toml` and/or `mkdocs.yml` files might have been diverged from the generated files and updated in a way that is not compatible with the upgrade. In that case you'll have to fix it manually or re-generate the templates.

## Bug Fixes

- CI / `mkdocs`: `mike` version sorting now properly sort pre-releases as older than stable releases for the same major and minor version.
- `cli.version.mike.info`: Don't fail if the version can't be determined, just emit a warning and exit succesfully.

### Cookiecutter template

- CI: The documentation publishing job will not fail if the version for `mike` can't be determined, it will just emit a warning and skip the publishing of the documentation website.
1 change: 1 addition & 0 deletions cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ plugins:
- literate-nav:
nav_file: SUMMARY.md
- mike:
alias_type: redirect
canonical_version: latest
- mkdocstrings:
custom_templates: templates
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
dev-mkdocs = [
"black == 23.9.1",
"Markdown==3.4.4",
"mike == 1.1.2",
"mike == 2.0.0",
"mkdocs-gen-files == 0.5.0",
"mkdocs-literate-nav == 0.6.1",
"mkdocs-macros-plugin == 1.0.4",
Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ plugins:
- literate-nav:
nav_file: SUMMARY.md
- mike:
alias_type: redirect
canonical_version: latest
- mkdocstrings:
custom_templates: templates
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
dev-mkdocs = [
"black == 23.9.1",
"Markdown==3.4.4",
"mike == 1.1.2",
"mike == 2.0.0",
"mkdocs-gen-files == 0.5.0",
"mkdocs-literate-nav == 0.6.1",
"mkdocs-macros-plugin == 1.0.4",
Expand Down
5 changes: 4 additions & 1 deletion src/frequenz/repo/config/cli/version/mike/info.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,10 @@ def main() -> None:
try:
mike_version = mike.build_mike_version(github.get_repo_version_info())
except ValueError as error:
github.abort(f"{error}.", title="Documentation was not published")
gha.warning(
f"{error}.", title="Could not determine the version information for `mike`"
)
return

_output_gha_vars(mike_version)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ plugins:
- literate-nav:
nav_file: SUMMARY.md
- mike:
alias_type: redirect
canonical_version: latest
- mkdocstrings:
custom_templates: templates
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
dev-mkdocs = [
"black == 23.9.1",
"Markdown==3.4.4",
"mike == 1.1.2",
"mike == 2.0.0",
"mkdocs-gen-files == 0.5.0",
"mkdocs-literate-nav == 0.6.1",
"mkdocs-macros-plugin == 1.0.4",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ plugins:
- literate-nav:
nav_file: SUMMARY.md
- mike:
alias_type: redirect
canonical_version: latest
- mkdocstrings:
custom_templates: templates
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
dev-mkdocs = [
"black == 23.9.1",
"Markdown==3.4.4",
"mike == 1.1.2",
"mike == 2.0.0",
"mkdocs-gen-files == 0.5.0",
"mkdocs-literate-nav == 0.6.1",
"mkdocs-macros-plugin == 1.0.4",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ plugins:
- literate-nav:
nav_file: SUMMARY.md
- mike:
alias_type: redirect
canonical_version: latest
- mkdocstrings:
custom_templates: templates
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
dev-mkdocs = [
"black == 23.9.1",
"Markdown==3.4.4",
"mike == 1.1.2",
"mike == 2.0.0",
"mkdocs-gen-files == 0.5.0",
"mkdocs-literate-nav == 0.6.1",
"mkdocs-macros-plugin == 1.0.4",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ plugins:
- literate-nav:
nav_file: SUMMARY.md
- mike:
alias_type: redirect
canonical_version: latest
- mkdocstrings:
custom_templates: templates
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
dev-mkdocs = [
"black == 23.9.1",
"Markdown==3.4.4",
"mike == 1.1.2",
"mike == 2.0.0",
"mkdocs-gen-files == 0.5.0",
"mkdocs-literate-nav == 0.6.1",
"mkdocs-macros-plugin == 1.0.4",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ plugins:
- literate-nav:
nav_file: SUMMARY.md
- mike:
alias_type: redirect
canonical_version: latest
- mkdocstrings:
custom_templates: templates
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
dev-mkdocs = [
"black == 23.9.1",
"Markdown==3.4.4",
"mike == 1.1.2",
"mike == 2.0.0",
"mkdocs-gen-files == 0.5.0",
"mkdocs-literate-nav == 0.6.1",
"mkdocs-macros-plugin == 1.0.4",
Expand Down

0 comments on commit 7e74141

Please sign in to comment.