docs: refactor to pyproject.toml, uv and subdirectory for markdown files

.github/workflows/cd-docs.yaml

@@ -15,27 +15,20 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup python
-        uses: actions/setup-python@v4
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v4
         with:
-          python-version: "3.10"
+          version: 'latest'
+          enable-cache: true
+          cache-dependency-glob: "docs/_kalico/uv.lock"
 
-      - uses: actions/cache@v4
-        id: pip-cache
-        with:
-          path: ${{ env.pythonLocation }}
-          key: ${{ runner.os }}-pip-${{ hashFiles('docs/_kalico/mkdocs-requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
-
-      - name: Install dependencies
-        if: steps.pip-cache.outputs.cache-hit != 'true'
-        run: pip install -r docs/_kalico/mkdocs-requirements.txt
+      - name: Setup Python
+        working-directory: docs/_kalico/
+        run: uv python install
 
       - name: Build MkDocs Pages
-        run: |
-          cd docs/
-          mkdocs build -f _kalico/mkdocs.yml
+        working-directory: docs/_kalico/
+        run: uv run mkdocs build
 
       - name: Deploy
         uses: JamesIves/[email protected]

.github/workflows/ci-docs_test.yaml

@@ -11,24 +11,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup python
-        uses: actions/setup-python@v4
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v4
         with:
-          python-version: "3.10"
+          version: 'latest'
+          enable-cache: true
+          cache-dependency-glob: "docs/_kalico/uv.lock"
 
-      - uses: actions/cache@v4
-        id: pip-cache
-        with:
-          path: ${{ env.pythonLocation }}
-          key: ${{ runner.os }}-pip-${{ hashFiles('docs/_kalico/mkdocs-requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
-
-      - name: Install dependencies
-        if: steps.pip-cache.outputs.cache-hit != 'true'
-        run: pip install -r docs/_kalico/mkdocs-requirements.txt
+      - name: Setup Python
+        working-directory: docs/_kalico/
+        run: uv python install
 
       - name: Build MkDocs Pages
-        run: |
-          cd docs/
-          mkdocs build -f _kalico/mkdocs.yml --strict
+        working-directory: docs/_kalico/
+        run: uv run mkdocs build --strict

docs/_kalico/.python-version

@@ -0,0 +1 @@
+3.13

docs/_kalico/README

@@ -5,8 +5,12 @@ https://www.mkdocs.org/ ) to automatically convert the markdown files
 in the docs/ directory to html. In addition to the files in this
 directory, the docs/CNAME file also controls the website generation.
 
-To test deploy the main English site locally one can use commands
+To test deploy the main site locally one can use commands
 similar to the following:
 
-virtualenv ~/mkdocs-env && ~/python-env/bin/pip install -r ~/kalico/docs/_kalico/mkdocs-requirements.txt
-cd ~/kalico && ~/mkdocs-env/bin/mkdocs serve --config-file ~/kalico/docs/_kalico/mkdocs.yml -a 0.0.0.0:8000
+```bash
+cd docs/_kalico/ # if you were in the repo root
+uv venv
+uv sync
+uv run mkdocs serve
+```

docs/_kalico/mkdocs.yml

@@ -31,7 +31,7 @@ plugins:
     lang: en
   mkdocs-simple-hooks:
     hooks:
-      on_page_markdown: "docs._kalico.mkdocs_hooks:transform"
+      on_page_markdown: "mkdocs_hooks:transform"
   gh-admonitions:
   redirects:
     redirect_maps:
@@ -78,7 +78,7 @@ extra_css:
 
 extra:
   social:
-    - icon: fontawesome/brands/discord 
+    - icon: fontawesome/brands/discord
       link: https://kalico.gg/discord
       name: Join our Discord server!
   # Site usage statistics

docs/_kalico/mkdocs_hooks.py

@@ -22,13 +22,13 @@ def transform(markdown: str, page, config, files):
     for i in range(len(lines)):
         line_out = lines[i]
         in_code_block = (
-            in_code_block + len(re.findall("\s*[`]{3,}", line_out))
+            in_code_block + len(re.findall(r"\s*[`]{3,}", line_out))
         ) % 2
         if not in_code_block:
             line_out = line_out.replace(
                 "](../", f"]({config['repo_url']}/blob/main/"
             )
-            line_out = re.sub("\\\s*$", "<br>", line_out)
+            line_out = re.sub(r"\\\s*$", "<br>", line_out)
             # check that lists at level 0 are not indented
             # (no space before *|-|1.)
             if re.match(r"^[^-*0-9 ]", line_out):

docs/_kalico/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "kalico-docs"
+version = "0.1.0"
+requires-python = ">=3.9"
+dependencies = [
+    # mkdocs + theme
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.5.49",
+    # mkdocs plugins
+    "mdx-breakless-lists>=1.0.1",
+    "mdx-truly-sane-lists>=1.3",
+    "mkdocs-exclude>=1.0.2",
+    "mkdocs-simple-hooks>=0.1.5",
+    "mkdocs-github-admonitions-plugin==0.0.3",
+    "mkdocs-redirects==1.2.2",
+    "py-gfm>=2.0.0",
+]
+
+[dependency-groups]
+dev = []