From 57461082843da3b7629237f86dbb219ad04c7a41 Mon Sep 17 00:00:00 2001 From: Junfeng Qiao Date: Sat, 17 Feb 2024 20:04:22 +0100 Subject: [PATCH 1/5] 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 9ae2103d..8bfbf61b 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 48655909..e129794a 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 df0de252..8864b42c 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 c44d18db..1e1b211c 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 00000000..0af326af --- /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 843f4cb6..f97e6506 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 From ccb67c7cfc2c6c46fca3cafbbb13bbe0dd32c192 Mon Sep 17 00:00:00 2001 From: Junfeng Qiao Date: Fri, 23 Feb 2024 18:56:12 +0100 Subject: [PATCH 2/5] Switch to readthedocs --- .github/workflows/docs.yml | 43 ------------------------------------ .readthedocs.yaml | 19 ++++++++++++++++ docs/README.md | 45 -------------------------------------- docs/mkdocs.yml | 19 +++++++++++----- docs/overrides/main.html | 8 ------- docs/requirements.txt | 1 - 6 files changed, 32 insertions(+), 103 deletions(-) delete mode 100644 .github/workflows/docs.yml create mode 100644 .readthedocs.yaml delete mode 100644 docs/overrides/main.html diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index 8bfbf61b..00000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,43 +0,0 @@ -name: Deploy docs - -on: - release: - types: [published] - -jobs: - 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: 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/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..8c42386e --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,19 @@ +# Read the Docs configuration file for MkDocs projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +mkdocs: + configuration: docs/mkdocs.yml + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/README.md b/docs/README.md index 8864b42c..df0de252 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,51 +24,6 @@ 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 1e1b211c..4c91c062 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -125,7 +125,6 @@ theme: code: Roboto Mono logo: assets/wannier-logo-squared.svg favicon: assets/wannier-logo-squared.png - custom_dir: overrides extra: status: @@ -137,8 +136,6 @@ extra: social: - icon: fontawesome/brands/github link: https://github.com/wannier-developers/wannier90 - version: - provider: mike markdown_extensions: - abbr @@ -202,8 +199,18 @@ plugins: - search - glightbox - bibtex: - bib_file: "refs.bib" - footnote_format: "ref{number}" # default "{number}", to avoid conflict with user-defined footnotes + # `bib_file` takes precedence over `bib_dir`, if `bib_file` is defined, + # the bibtex plugin will use an absolute path to the file, meaning that + # we can only execute `mkdocs build` in the folder `REPO_root/docs`. + # With `bib_dir` the bibtex plugin will use a relative path to the + # `mkdocs.yml` file, and search recursively for all the bib files. + # Therefore, it is possible to execute `mkdocs build` in both the + # `REPO_root` and the `REPO_root/docs` folder, then readthedocs can build + # the docs (since readthedocs always builds the docs in the `REPO_root`). + # bib_file: refs.bib + bib_dir: . + # default "{number}", to avoid conflict with user-defined footnotes + footnote_format: "ref{number}" extra_javascript: - javascripts/mathjax.js @@ -215,4 +222,4 @@ extra_javascript: extra_css: - stylesheets/custom.css - - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css + # - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css diff --git a/docs/overrides/main.html b/docs/overrides/main.html deleted file mode 100644 index 0af326af..00000000 --- a/docs/overrides/main.html +++ /dev/null @@ -1,8 +0,0 @@ -{% 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 f97e6506..843f4cb6 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,4 +5,3 @@ 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 From 6473dabb31c4e1d4e31255c42d5ede95e5afcd72 Mon Sep 17 00:00:00 2001 From: Junfeng Qiao Date: Wed, 28 Feb 2024 14:20:04 +0100 Subject: [PATCH 3/5] Update URLs --- README.rst | 4 ++-- docs/mkdocs.yml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 683d4ff5..016e97a0 100644 --- a/README.rst +++ b/README.rst @@ -5,7 +5,7 @@ Wannier90 The Maximally-Localised Generalised Wannier Functions Code ---------------------------------------------------------- -The homepage of the Wannier90 code is http://www.wannier.org +The homepage of the Wannier90 code is https://www.wannier.org The code is hosted on GitHub_. @@ -15,7 +15,7 @@ here_. .. _GitHub: https://github.com/wannier-developers/wannier90 -.. _here: https://wannier-developers.github.io/wannier90 +.. _here: https://wannier90.readthedocs.io/ How to contribute +++++++++++++++++ diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 4c91c062..cdf5848d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,5 +1,5 @@ site_name: Wannier90 Documentation -site_url: https://wannier-developers.github.io/wannier90/ +site_url: https://wannier90.readthedocs.io/ # site_url: https://wannier.org/ site_author: Wannier90 Developers site_description: >- From 7e39f1b80af25d4d75f695c3424c9d64daa61678 Mon Sep 17 00:00:00 2001 From: Junfeng Qiao Date: Wed, 28 Feb 2024 17:52:19 +0100 Subject: [PATCH 4/5] Add URL to old PDF docs & clean up github workflows --- .github/workflows/main.yml | 7 ++++--- .readthedocs.yaml | 6 ++---- docs/docs/index.md | 3 +++ 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index e129794a..818a186d 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -68,16 +68,17 @@ jobs: test-suite/tests/test*/test.out* docs: - name: Build docs + name: Validate mkdocs links runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: - python-version: "3.11" + # use the latest stable version + python-version: "3.x" cache: "pip" - run: pip install -r docs/requirements.txt - - run: mkdocs build -s + - run: mkdocs build --strict working-directory: ./docs env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 8c42386e..f3c8c1bb 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,19 +1,17 @@ # Read the Docs configuration file for MkDocs projects # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details -# Required version: 2 -# Set the version of Python and other tools you might need build: os: ubuntu-22.04 tools: - python: "3.12" + # latest 3.x version available on Read the Docs + python: "3" mkdocs: configuration: docs/mkdocs.yml -# Optionally declare the Python requirements required to build your docs python: install: - requirements: docs/requirements.txt diff --git a/docs/docs/index.md b/docs/docs/index.md index 20694010..af580036 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -18,3 +18,6 @@ This documentation contains the following sections: - [User guide](user_guide/introduction.md) - [Tutorials](tutorials/preliminaries.md) + +For historical reference, the old latex PDF documentation of Wannier90 v3.1 +can be found on the [Wannier90 website](https://wannier.org/support/). From 99cc773170e3a5e7a8e58fbcdc063dc429328a06 Mon Sep 17 00:00:00 2001 From: Junfeng Qiao Date: Fri, 1 Mar 2024 11:30:01 +0100 Subject: [PATCH 5/5] Fix for mkdocs-bibtex with python 3.12 Python 3.12 does not install `setuptools` in virtual env, therefore `pkg_resources` is missing but `mkdocs-bibtex` explicitly imports it. The solution is to explicitly install `setuptools` in the virtual env. See https://docs.python.org/3/whatsnew/3.12.html Co-authored-by: Cristian Le --- .github/workflows/main.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 818a186d..4b8520b0 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -77,7 +77,10 @@ jobs: # use the latest stable version python-version: "3.x" cache: "pip" - - run: pip install -r docs/requirements.txt + # `pybtex` uses `pkg_resources` which is deprecated. Use workaround until upstream `mkdocs_bibtext`decides on a solution + # https://github.com/shyamd/mkdocs-bibtex/issues/228 + # https://bitbucket.org/pybtex-devs/pybtex/issues/169/replace-pkg_resources-with + - run: pip install -r docs/requirements.txt setuptools - run: mkdocs build --strict working-directory: ./docs env: