Merge pull request wannier-developers#470 from qiaojunfeng/mkdocs

Migrate user guide/examples to mkdocs

.github/workflows/docs_ci.yml

@@ -0,0 +1,28 @@
+name: CI test docs
+on:
+  pull_request:
+    paths:
+      - docs/**
+
+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

.github/workflows/docs_deploy.yml

@@ -0,0 +1,19 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Deploy docs
+        uses: mhausenblas/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ENABLE_MKDOCS_GIT_COMMITTERS: True

.pre-commit-config.yaml

@@ -3,15 +3,24 @@ repos:
   rev: v4.1.0
   hooks:
   - id: check-yaml
+    exclude: (?x)^(
+        docs/mkdocs.yml
+      )$
+  - id: check-yaml
+    name: check yaml unsafe
+    args: ['--unsafe']
+    files: (?x)^(
+        docs/mkdocs.yml
+      )$
   - id: trailing-whitespace
     files: (?x)^(
         config/make[.]inc[.\w]*|
-        examples/example\d\d[-]?\w*/.+win
+        tutorials/tutorial\d\d[-]?\w*/.+win
       )$
   - id: end-of-file-fixer
     files: (?x)^(
         config/make[.]inc[.\w]*|
-        examples/example\d\d[-]?\w*/.+win
+        tutorials/tutorial\d\d[-]?\w*/.+win
       )$
 - repo: https://github.com/pseewald/fprettify
   rev: v0.3.3