From 0c498b43456005465fb1b55e2830b1b41836eb8e Mon Sep 17 00:00:00 2001 From: Alexander Voss Date: Thu, 28 Sep 2023 16:42:28 +0200 Subject: [PATCH] added instructions for checking out and updating specific releases (#6095) * added instructions for checking out specific releases and also moved the bit about $GH_TOKEN to a place above the pip install instructions * separated out update instructions, revised git instructions * bumped version number that insiders is based on * removed --upgrade from update command * made insiders changelog a section * changed instructions for upgrading via git --- .../{changelog.md => changelog/index.md} | 1 - docs/insiders/getting-started.md | 55 +++++++------- docs/insiders/upgrade.md | 74 +++++++++++++++++++ mkdocs.yml | 7 +- src/overrides/hooks/shortcodes.py | 2 +- 5 files changed, 105 insertions(+), 34 deletions(-) rename docs/insiders/{changelog.md => changelog/index.md} (99%) create mode 100644 docs/insiders/upgrade.md diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog/index.md similarity index 99% rename from docs/insiders/changelog.md rename to docs/insiders/changelog/index.md index a7d53c2ca..4b1e7749d 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog/index.md @@ -1,4 +1,3 @@ -# Changelog ## Material for MkDocs Insiders diff --git a/docs/insiders/getting-started.md b/docs/insiders/getting-started.md index d178e640a..cb6c19851 100644 --- a/docs/insiders/getting-started.md +++ b/docs/insiders/getting-started.md @@ -30,20 +30,38 @@ your GitHub account in order to access the Insiders repository programmatically [Generate a new token]: https://github.com/settings/tokens/new [scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes +Some of the instructions below require that the `GH_TOKEN` environment +variable is set to the value of the personal access token you +generated in the previous step. Note that the personal access token +must be kept secret at all times, as it allows the owner to access +your private repositories. + ## Installation ### with pip -Material for MkDocs Insiders can be installed with `pip`: +Material for MkDocs Insiders can be installed with `pip`. You will +normally want to install the latest release but can also install a +specific older release or even the latest development version. +Make sure you have the `GH_TOKEN` variable set as instructed above. -``` sh -pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git -``` +=== "Specific release" -The `GH_TOKEN` environment variable must be set to the value of the personal -access token you generated in the previous step. Note that the personal access -token must be kept secret at all times, as it allows the owner to access your -private repositories. + Pick the corresponding tag from the [list of tags] for the Insiders + repository. In the `pip` command below, replace the tag at the + end of the URL with the one you want. + + ``` sh + pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0 + ``` + +=== "Latest" + + ``` sh + pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git + ``` + +[list of tags]: https://github.com/squidfunk/mkdocs-material-insiders/tags ### with docker @@ -129,27 +147,6 @@ pip install -e mkdocs-material [Pull App]: https://github.com/apps/pull [publish]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/publish.yml -## Upgrading - -When upgrading Insiders, you should always check the version of Material for -MkDocs which makes up the first part of the version qualifier, e.g.Insiders -`4.x.x` is currently based on `8.x.x`: - -``` -8.x.x-insiders-4.x.x -``` - -If the major version increased, it's a good idea to consult the [upgrade -guide] and go through the steps to ensure your configuration is up to date and -all necessary changes have been made. If you installed Insiders via `pip`, you -can upgrade your installation with the following command: - -``` -pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git -``` - - [upgrade guide]: ../upgrade.md - ## Built-in plugins When you're using built-in plugins that are solely available via Insiders, diff --git a/docs/insiders/upgrade.md b/docs/insiders/upgrade.md new file mode 100644 index 000000000..d576dd501 --- /dev/null +++ b/docs/insiders/upgrade.md @@ -0,0 +1,74 @@ +# How to upgrade + +When upgrading Insiders, you should always check the version of Material for +MkDocs which makes up the first part of the version qualifier, e.g., Insiders +`4.x.x` is currently based on `9.x.x`: + +``` +9.x.x-insiders-4.x.x +``` + +If the major version increased, it's a good idea to consult the [upgrade +guide] and go through the steps to ensure your configuration is up to date and +all necessary changes have been made. + + [upgrade guide]: ../upgrade.md + [list of tags]: https://github.com/squidfunk/mkdocs-material-insiders/tags + +Depending on how you installed and what you want to upgrade to you +need to run different commands: + +=== "pip upgrade to release" + + If you installed Insiders via `pip` and you want to upgrade to a + specific release, pick the tag from the [list of tags] and replace + the tag at the end of the URL of the command given below: + + ``` + pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0 + ``` + +=== "pip upgrade to latest development" + + If you installed Insiders via `pip` and want to upgrade to the + latest development version, run: + + ``` + pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git + ``` + +=== "git upgrade" + + If you installed Insiders via `git`, you will first need to check + out the version you want to install into your workspace. After + this is done, you can run `pip` to install that version. + + First, make sure that your local clone is up-to-date with the + upstream repository by running `git pull`. + + You can look up the tags using `git tag --sort -refname` or you + can consult the [list of tags]. Then, checkout the tag you want to + use by replacing the one given in the command below (twice)and running + it from your workspace[^detached]: + + [^detached]: + The `--detach` argument serves to tell `git` that you are ok to + have your workspace in the [detached head] state, which is + perfectly fine to have here. + + [detached head]: https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit/ + + ``` + cd mkdocs-material + git checkout --detach tags/9.4.2-insiders-4.42.0 + ``` + + Now, change back to the parent directory in which your Git + repository lives and run `pip`: + + ``` + cd .. + pip install -e mkdocs-material + ``` + + diff --git a/mkdocs.yml b/mkdocs.yml index 10f93b3f6..a08669d82 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -252,8 +252,9 @@ nav: - Tooltips: reference/tooltips.md - Insiders: - insiders/index.md - - Getting started: - - Installation: insiders/getting-started.md - - Changelog: insiders/changelog.md + - Getting started: insiders/getting-started.md + - Changelog: + - insiders/changelog/index.md + - How to upgrade: insiders/upgrade.md - Blog: - blog/index.md diff --git a/src/overrides/hooks/shortcodes.py b/src/overrides/hooks/shortcodes.py index 574652042..5b02e3cfe 100644 --- a/src/overrides/hooks/shortcodes.py +++ b/src/overrides/hooks/shortcodes.py @@ -145,7 +145,7 @@ def _badge_for_version(text: str, page: Page, files: Files): # Create badge for version of Insiders def _badge_for_version_insiders(text: str, page: Page, files: Files): spec = text.replace("insiders-", "") - path = f"insiders/changelog.md#{spec}" + path = f"insiders/changelog/index.md#{spec}" # Return badge icon = "material-tag-heart-outline"