docs: align docs tooling and doc_env workflow

.github/workflows/deploy-docs.yaml

@@ -10,6 +10,7 @@ on:
       - "**/*.svg"
       - "**/*.png"
       - "**/*.jpg"
+      - "docs/assets/**"
   workflow_dispatch:
 
 permissions:
@@ -41,12 +42,10 @@ jobs:
           pip install mkdocs-awesome-pages-plugin
           pip install mkdocs-exclude
           pip install mkdocs-macros-plugin
-          pip install mkdocs-same-dir
           pip install pymdown-extensions
           pip install python-markdown-math
           pip install mdx-truly-sane-lists
           pip install plantuml-markdown
-          pip install mkdocs-mermaid2-plugin
 
       - name: Build with MkDocs
         run: mkdocs build --clean --verbose
@@ -83,4 +82,3 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
-

Makefile

@@ -1,23 +1,24 @@
-# Makefile for Openadkit Document
+# Makefile for Open AD Kit documentation
 # Installs required MkDocs packages and serves documentation
 
-.PHONY: help prepare serve build clean
+.PHONY: help prepare prepare-if-missing serve build clean
 
 # Default target
 help:
-	@echo "Openadkit Documentation - Available commands:"
+	@echo "Open AD Kit Documentation - Available commands:"
 	@echo "  make prepare      Prepare Mkdocs development container"
+	@echo "  make prepare-if-missing  Reuse local image if present, otherwise build it"
 	@echo "  make serve        Start development server on the built container"
 	@echo "  make build        Build static documentation"
 	@echo "  make clean        Clean build artifacts"
 
 # Serve documentation locally
 serve:
-	docker run -it --rm -p 8000:8000 -v $$(pwd):/app mkdocs-dev
+	docker run --rm -p 8000:8000 -v $$(pwd):/app mkdocs-dev
 
 # Build static documentation
 build:
-	docker run -it --rm -v $$(pwd):/app --user $$(id -u):$$(id -g) mkdocs-dev mkdocs build
+	docker run --rm -v $$(pwd):/app --user $$(id -u):$$(id -g) mkdocs-dev mkdocs build
 
 # Clean build artifacts
 clean:
@@ -26,3 +27,11 @@ clean:
 # Install mkdocs dependencies
 prepare:
 	docker build -f doc_env/Dockerfile -t mkdocs-dev .
+
+# Reuse an existing image when offline or when rebuilding is unnecessary
+prepare-if-missing:
+	@if docker image inspect mkdocs-dev >/dev/null 2>&1; then \
+		echo "Using existing mkdocs-dev image"; \
+	else \
+		docker build -f doc_env/Dockerfile -t mkdocs-dev .; \
+	fi

doc_env/Dockerfile

@@ -7,12 +7,10 @@ RUN pip install --no-cache-dir \
     mkdocs-awesome-pages-plugin \
     mkdocs-exclude \
     mkdocs-macros-plugin \
-    mkdocs-same-dir \
     pymdown-extensions \
     python-markdown-math \
     mdx-truly-sane-lists \
-    plantuml-markdown \
-    mkdocs-mermaid2-plugin
+    plantuml-markdown
 
 EXPOSE 8000
 

doc_env/README.md

@@ -1,17 +1,17 @@
-# Openadkit: Containerized MkDocs Development
+# Open AD Kit: Containerized MkDocs Development
 
-This document explains how to set up a containerized development environment for MkDocs in the Openadkit project using Docker and Makefile. The `doc_env/Dockerfile` and `Makefile` are designed to replicate the dependencies and configuration used in the project's GitHub Actions workflow, ensuring consistency between local development and CI/CD environments.
+This document explains how to set up a containerized development environment for MkDocs in the Open AD Kit project using Docker and Makefile. The `doc_env/Dockerfile` and `Makefile` are designed to replicate the dependencies and configuration used in the project's GitHub Actions workflow, ensuring consistency between local development and CI/CD environments.
 
 ## TL;DR
 
-In the Openadkit project **root directory**:
+In the Open AD Kit project **root directory**:
 
 ```bash
 make prepare
 make serve
 ```
 
-Access the MkDocs development server at `http://localhost:8000`. To build the static site:
+Access the MkDocs development server at `http://localhost:8000/openadkit/`. To build the static site:
 
 ```bash
 make build
@@ -26,8 +26,9 @@ make build
 
 The `Makefile` simplifies common tasks for managing the MkDocs environment. Available commands:
 
-- `make prepare`: Builds the Docker image with required MkDocs dependencies.
-- `make serve`: Starts the MkDocs development server at `http://localhost:8000`.
+- `make prepare`: Rebuilds the Docker image with required MkDocs dependencies.
+- `make prepare-if-missing`: Reuses an existing `mkdocs-dev` image if present, otherwise builds it.
+- `make serve`: Starts the MkDocs development server at `http://localhost:8000/openadkit/`.
 - `make build`: Generates the static site in the `site/` directory with correct permissions.
 - `make clean`: Removes the `site/` directory to clean up build artifacts.
 - `make help`: Displays available commands.
@@ -36,19 +37,21 @@ Run `make help` to see all options.
 
 ## Setup and Usage
 
-1. **Build the Docker Image**
+1. **Prepare the Docker Image**
 
    Run the following command to build the Docker image:
 
    ```bash
    make prepare
    ```
 
-   This builds the `mkdocs-dev` image using the `doc_env/Dockerfile`, which includes:
-   - Base image: `python:3.11-slim`
-   - Installed MkDocs plugins: `mkdocs-material`, `mkdocs-awesome-pages-plugin`, `mkdocs-exclude`, `mkdocs-macros-plugin`, `mkdocs-same-dir`, `pymdown-extensions`, `python-markdown-math`, `mdx-truly-sane-lists`, `plantuml-markdown`, `mkdocs-mermaid2-plugin`
-   - Working directory: `/app`
-   - Exposed port: `8000`
+    This builds the `mkdocs-dev` image using the `doc_env/Dockerfile`, which includes:
+    - Base image: `python:3.11-slim`
+    - Installed MkDocs plugins: `mkdocs-material`, `mkdocs-awesome-pages-plugin`, `mkdocs-exclude`, `mkdocs-macros-plugin`, `pymdown-extensions`, `python-markdown-math`, `mdx-truly-sane-lists`, `plantuml-markdown`
+    - Working directory: `/app`
+    - Exposed port: `8000`
+
+    Use `make prepare-if-missing` only when you intentionally want to reuse an existing local image, such as during offline verification.
 
 2. **Run the Development Server**
 
@@ -58,7 +61,7 @@ Run `make help` to see all options.
    make serve
    ```
 
-   - Opens `http://localhost:8000` in your browser to view the live site.
+   - Opens `http://localhost:8000/openadkit/` in your browser to view the live site.
    - Changes to `docs/` or `mkdocs.yaml` trigger automatic reloading.
    - The current directory is mounted to `/app` in the container for live updates.
 
@@ -86,18 +89,13 @@ Run `make help` to see all options.
 
 - **File Permissions**: The `make build` command uses `--user $(id -u):$(id -g)` to ensure the `site/` directory has the same ownership as your host user, avoiding permission issues on Linux systems.
 - **Customizing Plugins**: Update both `doc_env/Dockerfile` and `mkdocs.yaml` if additional MkDocs plugins are needed.
-- **Optimizing Builds**: Use a `.dockerignore` file to exclude unnecessary files (e.g., `site/`, `.github/`) to reduce build time. Example `.dockerignore`:
-  ```
-  .github/
-  deployments/
-  site/
-  ```
 - **Cleaning Up Docker**: Use `docker system prune` to remove unused images and containers.
-- **Documentation**: Refer to `docs/dev/index.md` for additional development environment details.
+- **Documentation Source**: The published documentation lives under `docs/` and is configured by `mkdocs.yaml`.
 
 ## Troubleshooting
 
 - **Permission Issues**: If the `site/` directory has incorrect permissions, ensure `make build` is used instead of directly running `docker run ... mkdocs build`.
 - **Port Conflicts**: If port `8000` is in use, stop other services or change the port mapping (e.g., `-p 8001:8000` in the `make serve` command by editing the `Makefile`).
+- **Prepare Fails During Package Download**: If Docker cannot reach PyPI while building `mkdocs-dev`, rerun `make prepare` once network access is available. If you already have a suitable local image and only need to test docs content, use `make prepare-if-missing`.
 
-For further assistance, consult the main `README.md` or open an issue in the Openadkit repository.
+For further assistance, consult the main `README.md` or open an issue in the Open AD Kit repository.