From 6ad1b49067324999f9f47745ad147774dba3ccda Mon Sep 17 00:00:00 2001 From: Junfeng Qiao Date: Sat, 17 Feb 2024 20:04:22 +0100 Subject: [PATCH] Use mike for docs versioning - Add version warning - Auto deploy docs to `gh-pages` on github release The commit is kept here as a reference. We will switch to readthedocs to deploy multiple versions of the docs, since mike use `gh-pages` branch to host the docs, increasing the size of the repo in the long term. See #485 for more details. --- .github/workflows/docs.yml | 71 +++++++++++++++++++++----------------- .github/workflows/main.yml | 22 ++++++++++-- docs/README.md | 45 ++++++++++++++++++++++++ docs/mkdocs.yml | 3 ++ docs/overrides/main.html | 8 +++++ docs/requirements.txt | 1 + 6 files changed, 115 insertions(+), 35 deletions(-) create mode 100644 docs/overrides/main.html diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9ae2103d8..8bfbf61bf 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,36 +1,43 @@ -name: Build docs +name: Deploy docs + on: - pull_request: - push: - branches: - - develop + release: + types: [published] jobs: - docs: - name: Build docs - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: "3.11" - - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV - - uses: actions/cache@v4 - with: - key: mkdocs-w90-${{ env.cache_id }} - path: .cache - restore-keys: | - mkdocs-w90- - - run: pip install -r docs/requirements.txt - - run: mkdocs build -s - working-directory: ./docs - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - ENABLE_MKDOCS_GIT_COMMITTERS: False + deploy_docs: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: git fetch origin gh-pages --depth=1 + - run: | + git config user.name github-actions + git config user.email github-actions@github.com + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + cache: "pip" + - run: pip install -r docs/requirements.txt + + # This deploys mkdocs-built html, now we use mike to deploy + # html to have doc versioning. + # + # - run: mkdocs build -s + # working-directory: ./docs + # env: + # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # ENABLE_MKDOCS_GIT_COMMITTERS: True + # - name: Deploy to GitHub Pages + # uses: peaceiris/actions-gh-pages@v3 + # if: github.ref == 'refs/heads/develop' + # with: + # github_token: ${{ secrets.GITHUB_TOKEN }} + # publish_dir: ./docs/site - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@v3 - if: github.ref == 'refs/heads/develop' - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/site + - name: mike deploy + run: mike deploy --push --update-aliases ${{ github.ref_name }} latest + working-directory: ./docs + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + ENABLE_MKDOCS_GIT_COMMITTERS: True diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 4d850d6f2..0ae5ab1ef 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -4,8 +4,8 @@ on: pull_request: push: branches: - - develop - + - develop + jobs: pre-commit: runs-on: ubuntu-20.04 @@ -18,7 +18,7 @@ jobs: runs-on: ubuntu-20.04 strategy: matrix: - w90-binary-parallel: [ 'false', 'true' ] + w90-binary-parallel: ["false", "true"] name: Build and test `parallel=${{ matrix.w90-binary-parallel }}` steps: - name: checkout @@ -66,3 +66,19 @@ jobs: path: | test-suite/tests/test*/test.err* test-suite/tests/test*/test.out* + + docs: + name: Build docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + cache: "pip" + - run: pip install -r docs/requirements.txt + - run: mkdocs build -s + working-directory: ./docs + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + ENABLE_MKDOCS_GIT_COMMITTERS: False diff --git a/docs/README.md b/docs/README.md index df0de2522..8864b42cc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,6 +24,51 @@ pip install -r requirements.txt * `mkdocs build` - Build the documentation site. * `mkdocs -h` - Print help message and exit. +## Versioning + +[`mike`](https://github.com/jimporter/mike) is used to manage the versioning of +the documentation. + +In general, one can manually deploy the docs when a new version is released, by + +```bash +mike deploy --push --update-aliases v[MAJOR].[MINOR] latest +``` + +Then the docs will be committed and pushed to the `gh-pages` branch. + +For development, one can use + +```bash +mike serve +``` + +To list the available versions, use + +```bash +mike list +``` + +### `miki` initialization + +For future reference, these are the commands used for initializing the +`gh-pages` branch + +```bash +mike delete --all # clean gh-pages branch +mike deploy --push --update-aliases v3.1.0 latest # build docs +mike set-default latest # set default redirect to latest +``` + +No need to run these commands again! +For future releases, just use `mike deploy`. + +### References + +* +* +* + ## Notes on conversion The original wannier90 latex documentation was converted to markdown using diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c44d18db4..1e1b211c6 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -125,6 +125,7 @@ theme: code: Roboto Mono logo: assets/wannier-logo-squared.svg favicon: assets/wannier-logo-squared.png + custom_dir: overrides extra: status: @@ -136,6 +137,8 @@ extra: social: - icon: fontawesome/brands/github link: https://github.com/wannier-developers/wannier90 + version: + provider: mike markdown_extensions: - abbr diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 000000000..0af326afb --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block outdated %} + You're not viewing the latest version. + + Click here to go to latest. + +{% endblock %} diff --git a/docs/requirements.txt b/docs/requirements.txt index 843f4cb6a..f97e6506f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,3 +5,4 @@ mkdocs-git-revision-date-localized-plugin==1.2.4 mkdocs-git-committers-plugin-2==2.2.3 mkdocs-bibtex==2.12.0 mkdocs-glightbox==0.3.7 +mike==2.0.0