feat: enhance documentation setup and update dependencies in pyprojec…

…t.toml

.github/workflows/docs.yaml

@@ -12,15 +12,7 @@ jobs:
       deployments: write
       statuses: write
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: 3.x
-      - uses: actions/cache@v2
-        with:
-          key: ${{ github.ref }}
-          path: .cache
-      - run: pip install mkdocs-material
-      - run: pip install pillow cairosvg
-      - run: python ./pre_docs.py
-      - run: mkdocs gh-deploy --force
+      - uses: actions/checkout@v4
+      - name: setup-steps
+        uses: "./.github/templates/setup-steps"
+      - run: just docs "gh-deploy --force"

justfile

@@ -34,3 +34,6 @@ pre-release: build
   uv pip sync --python .venv-ci/bin/python .venv-ci/requirements.txt
   uv pip install --python .venv-ci/bin/python -r .venv-ci/requirements.txt
   .venv-ci/bin/python scripts/model_lib_pre_release.py
+docs command='serve':
+  uv run scripts/pre_docs.py
+  mkdocs {{command}}

mkdocs.yml

@@ -39,12 +39,15 @@ extra:
     - icon: fontawesome/brands/github-alt
       link: https://github.com/EspenAlbert
 
+not_in_nav: |
+  _pants/*
+  compose_chart_export/*
+  docker_compose_parser/*
+
 nav:
 - Get Started: index.md
-- Model Lib: model_lib
-- Compose Chart Export: compose_chart_export
-- Docker Compose Parser: docker_compose_parser
-- zero-3rdparty: zero_3rdparty
+- Model Lib: model-lib/index.md
+- Zero 3rdparty: zero-3rdparty/index.md
 
 
 markdown_extensions:

pyproject.toml

@@ -57,4 +57,7 @@ dev = [
     "pyright>=1.1.392.post0",
     "pytest-freezer>=0.4.9",
     "ruff>=0.9.2",
+    "mkdocs-material>=9.5.50",
+    "pillow>=11.1.0",
+    "cairosvg>=2.7.1",
 ]

readme.md

@@ -21,16 +21,16 @@
 
 </p>
 
-# py-libs
+# py-libs (drastic changes coming for v1.0.0)
 
 - An experiment for sharing python packages
 - [compose_chart_export](./compose_chart_export/readme.md)
 	- `pip install compose-chart-export`
 - [docker_compose_parser](./docker_compose_parser/readme.md)
 	- `pip install docker-compose-parser`
-- [model_lib-pydantic base models with convenient dump methods](./model_lib/readme.md)
+- [model_lib-pydantic base models with convenient dump methods](./model-lib/readme.md)
 	- `pip install model-lib`
-- [zero_lib-handy standalone scripts without 3rdparty dependencies](./zero_3rdparty/readme.md)
+- [zero_lib-handy standalone scripts without 3rdparty dependencies](./zero-3rdparty/readme.md)
 	- `pip install zero-3rdparty`
 
 ## Hierarchy
@@ -44,8 +44,8 @@ flowchart TD
     pants_py_deploy --> compose_chart_export
     pants_py_deploy --> docker_compose_parser
 
-    click zero_3rdparty href "/py-libs/zero_3rdparty" "zero_3rdparty docs"
-    click model_lib href "/py-libs/model_lib" "model_lib docs"
+    click zero_3rdparty href "/py-libs/zero-3rdparty" "zero_3rdparty docs"
+    click model_lib href "/py-libs/model-lib" "model_lib docs"
     click docker_compose_parser href "/py-libs/docker_compose_parser" "docker_compose_parser docs"
     click compose_chart_export href "/py-libs/compose_chart_export" "compose_chart_export docs"
     click pants_py_deploy href "/py-libs/_pants/pants_py_deploy" "pants_py_deploy docs"
@@ -57,11 +57,10 @@ flowchart TD
 
 ## Local Installation
 
-- [Install pants](https://www.pantsbuild.org/v2.17/docs/installation)
-	- `brew install pantsbuild/tap/pants`
+- [Install `just`](https://just.systems/man/en/introduction.html)
+- [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
 
-```shell
-export PANTS_PYTHON_RESOLVES_TO_INTERPRETER_CONSTRAINTS="{'python-default': ['==3.10.*']}" # choose the version of python you like
-pants export --export-resolve=python-default
-# import the venv to pycharm/vs code, e.g., dist/export/python/virtualenvs/python-default/3.10.12
+```sh
+uv sync
+code .
 ```

scripts/pre_docs.py

@@ -0,0 +1,34 @@
+import shutil
+from pathlib import Path
+from typing import Iterable
+
+SRC = Path(__file__).parent.parent
+DOCS_DIR = SRC / "docs"
+IGNORED_MD_DIRECTORIES = [".pytest_cache", "test", "dist", ".venv",]
+
+FILENAME_RENAME = {"readme.md": "index.md"}
+
+
+def ignore_md_path(rel_path: str) -> bool:
+    return any(f"{d}/" in rel_path for d in IGNORED_MD_DIRECTORIES)
+
+
+def add_dest_paths(src_path: Path, md_dest_path: Path) -> Iterable[Path]:
+    if new_name := FILENAME_RENAME.get(md_dest_path.name):
+        yield md_dest_path.parent / new_name
+    yield md_dest_path
+
+
+def move_md_files():
+    for md_src_path in SRC.rglob("*.md"):
+        rel_path = str(md_src_path.relative_to(SRC))
+        if md_src_path.is_relative_to(DOCS_DIR) or ignore_md_path(rel_path):
+            continue
+        md_dest_path = DOCS_DIR / rel_path
+        for final_dest_path in add_dest_paths(md_src_path, md_dest_path):
+            final_dest_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy(md_src_path, final_dest_path)
+
+
+if __name__ == "__main__":
+    move_md_files()