switch to mkdocs (#50)

* switch to mkdocs

* Update docs/gen_cli_doc.py

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update comment in docs/src/lib.rs

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* update name of CI  job's step

* add to social icons

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: 2bndy5

.config/.readthedocs.yaml

@@ -9,20 +9,16 @@ build:
   os: ubuntu-22.04
   tools:
     rust: latest
-  commands:
-    # install cargo-binstall
-    - >-
-      curl
-      -L --proto '=https' --tlsv1.2 -sSf
-      https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh
-      | bash
-    # add .cargo bin to PATH
-    # install mdbook and mdbook-alerts
-    # build docs
-    - >-
-      PATH=/home/docs/.cargo/bin:$PATH &&
-      cargo binstall --install-path /home/docs/.cargo/bin -y mdbook mdbook-alerts &&
-      mdbook build docs
-    # move HTML output to required RTD output path
-    - mkdir -p ${READTHEDOCS_OUTPUT}
-    - mv docs/book/html/ "${READTHEDOCS_OUTPUT}"
+    python: latest
+
+mkdocs:
+  configuration: docs/mkdocs.yml
+
+
+# Optionally declare the Python requirements required to build your docs
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: docs/

.github/workflows/build-docs.yml

@@ -36,7 +36,7 @@ jobs:
           key: ${{ runner.os }}-docs-cargo-${{ hashFiles('Cargo.lock') }}
       - run: cargo fetch
 
-  build-mdbook:
+  build-mkdocs:
     runs-on: ubuntu-latest
     needs: [cache-deps]
     permissions:
@@ -48,26 +48,30 @@ jobs:
         with:
           path: ~/.cargo
           key: ${{ runner.os }}-docs-cargo-${{ hashFiles('Cargo.lock') }}
-      - name: Install mdbook
-        uses: taiki-e/install-action@v2
+      - uses: actions/setup-python@v5
         with:
-          tool: mdbook,cargo-binstall,just
-      - name: Install mdbook plugins
-        run: cargo binstall -y mdbook-alerts
-      - name: Build book
-        run: just docs-build
+          python-version: 3.x
+          cache: 'pip'
+          cache-dependency-path: docs/requirements.txt
+      - name: Install workflow deps
+        run: |
+          pip install -r docs/requirements.txt
+          pip install --force-reinstall -v docs/
+      - name: Build docs
+        working-directory: docs
+        run: mkdocs build
       - name: Upload docs build as artifact
         uses: actions/upload-artifact@v4
         with:
           name: cpp-linter-docs
-          path: docs/book/html
+          path: docs/site
       - name: Upload to github pages
         # only publish doc changes from main branch
         if: github.ref == 'refs/heads/main'
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/book/html
+          publish_dir: docs/site
 
   build-rustdoc:
     runs-on: ubuntu-latest
@@ -80,7 +84,7 @@ jobs:
         with:
           path: ~/.cargo
           key: ${{ runner.os }}-docs-cargo-${{ hashFiles('Cargo.lock') }}
-      - name: Install mdbook
+      - name: Install just
         uses: taiki-e/install-action@v2
         with:
           tool: just

.gitignore

@@ -338,8 +338,8 @@ debug/
 !.vscode/tasks.json
 !.vscode/extensions.json
 
-# mdbook builds
-book
+# mkdocs builds
+docs/site
 
 # ignore generated files
 .cpp-linter_cache/

.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
       - id: check-added-large-files
         args: [--maxkb=9000]
       - id: check-yaml
+        exclude: docs/mkdocs.yml
       - id: check-toml
       - id: requirements-txt-fixer
       - id: mixed-line-ending

.vscode/tasks.json

@@ -161,24 +161,25 @@
 		},
 		{
 			"type": "shell",
-			"command": "mdbook",
-			"label": "mdbook: serve",
+			"command": "mkdocs",
+			"label": "mkdocs: serve",
 			"args": [
 				"serve",
-				"docs",
+				" --config-file",
+				"docs/mkdocs.yml",
 				"--open"
 			],
 			"problemMatcher": [],
 			"group": "build"
 		},
 		{
 			"type": "shell",
-			"command": "mdbook",
-			"label": "mdbook: build",
+			"command": "mkdocs",
+			"label": "mkdocs: build",
 			"args": [
 				"build",
-				"docs",
-				"--open"
+				" --config-file",
+				"docs/mkdocs.yml"
 			],
 			"presentation": {
 				"close": true,