Merge pull request wannier-developers#493 from qiaojunfeng/rtd

Use readthedocs for documentation

.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,23 @@ jobs:
           path: |
             test-suite/tests/test*/test.err*
             test-suite/tests/test*/test.out*
+
+  docs:
+    name: Validate mkdocs links
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          # use the latest stable version
+          python-version: "3.x"
+          cache: "pip"
+      # `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:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ENABLE_MKDOCS_GIT_COMMITTERS: False

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    # latest 3.x version available on Read the Docs
+    python: "3"
+
+mkdocs:
+  configuration: docs/mkdocs.yml
+
+python:
+  install:
+  - requirements: docs/requirements.txt

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
 +++++++++++++++++

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/).

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: >-
@@ -199,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
@@ -212,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