Switch to readthedocs

.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

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
-
-* <https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning>
-* <https://github.com/squidfunk/mkdocs-material-example-versioning>
-* <https://github.com/jimporter/mike>
-
 ## Notes on conversion
 
 The original wannier90 latex documentation was converted to markdown using

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

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