Feature/new docs

.github/workflows/docs.yml

@@ -0,0 +1,81 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches:
+      - main
+      - master
+    paths:
+      - 'docs/**'
+  workflow_dispatch:  # Allow manual trigger
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for git-based plugins
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: |
+          cd docs
+          mkdocs build --strict
+
+      - name: Upload build artifact
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: docs/site/
+          retention-days: 7
+
+  deploy:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Deploy to GitHub Pages
+        run: |
+          cd docs
+          mkdocs gh-deploy --force --config-file mkdocs.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -26,3 +26,4 @@ pkg/
 *.pyc
 venv/
 python/probing/probing
+docs/site/

.pre-commit-config.yaml

@@ -5,6 +5,7 @@ repos:
     rev: v4.5.0
     hooks:
       - id: check-yaml
+        exclude: ^docs/mkdocs\.yml$  # mkdocs.yml uses !!python/name tags
       - id: check-toml
       - id: end-of-file-fixer
       - id: trailing-whitespace
@@ -20,12 +21,12 @@ repos:
     hooks:
       - id: black
 
-  - repo: local
-    hooks:
-      - id: cargo-fmt
-        name: cargo fmt
-        description: Format Rust code
-        entry: cargo fmt
-        language: system
-        types: [rust]
-        pass_filenames: false
+  # - repo: local
+  #   hooks:
+  #     - id: cargo-fmt
+  #       name: cargo fmt
+  #       description: Format Rust code
+  #       entry: cargo fmt
+  #       language: system
+  #       types: [rust]
+  #       pass_filenames: false

docs/Makefile

@@ -1,29 +1,40 @@
-# Minimal makefile for Sphinx documentation
-#
+# Makefile for Probing Documentation (MkDocs)
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD  ?= sphinx-build
-SOURCEDIR    = .
-BUILDDIR     = _build
+.PHONY: help install serve build clean deploy
 
-# Put it first so that "make" without argument is like "make help".
+# Default target
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Probing Documentation Build System"
 	@echo ""
-	@echo "Additional targets:"
-	@echo "  serve      Start live preview server with auto-reload"
+	@echo "Usage:"
+	@echo "  make install   Install documentation dependencies"
+	@echo "  make serve     Start live preview server with auto-reload"
+	@echo "  make build     Build static documentation site"
+	@echo "  make clean     Remove built documentation"
+	@echo "  make deploy    Deploy to GitHub Pages"
 
-.PHONY: help Makefile serve
+# Install dependencies
+install:
+	@echo "Installing documentation dependencies..."
+	pip install mkdocs mkdocs-material mkdocs-material-extensions mkdocstrings mkdocstrings-python
 
 # Live preview server
 serve:
 	@echo "Starting live preview server..."
 	@echo "Open http://127.0.0.1:8000 in your browser"
-	@sphinx-autobuild -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" --host 0.0.0.0 --port 8000 --open-browser
+	mkdocs serve --dev-addr 0.0.0.0:8000
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+# Build static site
+build:
+	@echo "Building documentation..."
+	mkdocs build
+
+# Clean build artifacts
+clean:
+	@echo "Cleaning build artifacts..."
+	rm -rf site/
+
+# Deploy to GitHub Pages
+deploy:
+	@echo "Deploying to GitHub Pages..."
+	mkdocs gh-deploy --force

docs/README.md

@@ -1,173 +1,90 @@
-# Probing Documentation System
+# Probing Documentation
 
-This directory contains the complete documentation for the Probing project, built using [Sphinx](https://www.sphinx-doc.org/).
+This directory contains the documentation for Probing, built with [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/).
 
 ## Quick Start
 
 ### Install Dependencies
 
 ```bash
-pip install -r requirements_doc.txt
+# Using pip
+pip install mkdocs mkdocs-material mkdocs-material-extensions mkdocstrings mkdocstrings-python
+
+# Or using uv
+uv pip install -r pyproject.toml
 ```
 
-### Build Documentation
+### Build and Serve
 
 ```bash
-# Build HTML documentation
-make html
+# Start live preview server
+make serve
 
-# Or use sphinx-build directly
-sphinx-build -b html . _build/html
+# Or directly with mkdocs
+mkdocs serve
 ```
 
-After building, the documentation will be generated in the `_build/html/` directory. Open `_build/html/index.html` in your browser to view the documentation.
-
-### Live Preview (Development Mode)
+Then open http://localhost:8000 in your browser.
 
-Using `sphinx-autobuild` can automatically detect file changes and rebuild the documentation while refreshing the browser:
+### Build Static Site
 
 ```bash
-# Method 1: Start from project root (recommended)
-make docs-serve
-
-# Method 2: Use convenience script in docs directory
-cd docs && ./serve.sh
-
-# Method 3: Use Makefile in docs directory
-cd docs && make serve
-
-# Method 4: Use sphinx-autobuild directly
-cd docs && sphinx-autobuild . _build/html --host 0.0.0.0 --port 8000 --open-browser
+make build
 ```
 
-After starting, the terminal will display the local access address (usually `http://127.0.0.1:8000`). Open it in your browser to view the documentation in real-time. After modifying any documentation files, the documentation will automatically rebuild and refresh the browser.
+The built site will be in the `site/` directory.
 
-**Common Options:**
-- `--host 0.0.0.0` - Allow access from other devices (on local network)
-- `--port 8000` - Specify port number (default 8000)
-- `--open-browser` - Automatically open browser
-
-## Documentation Structure
+## Directory Structure
 
 ```
 docs/
-├── conf.py              # Sphinx configuration file
-├── index.rst            # Main documentation index
-├── requirements_doc.txt # Python dependencies (documentation build only)
-├── Makefile            # Build script (Unix)
-├── getting-started/    # Getting started guide
-├── user-guide/         # User guide
-├── design/             # System design
-├── advanced/           # Advanced topics
-└── development/        # Development related
+├── mkdocs.yml           # MkDocs configuration
+├── pyproject.toml       # Python dependencies
+├── Makefile             # Build commands
+├── overrides/           # Custom templates
+│   └── home.html        # Homepage template
+└── src/                 # Documentation source
+    ├── index.md         # Homepage content
+    ├── installation.md  # Installation guide
+    ├── quickstart.md    # Quick start guide
+    ├── guide/           # User guide
+    ├── design/          # Design documents
+    ├── examples/        # Example workflows
+    ├── api-reference.md # API reference
+    └── assets/          # Static assets
+        └── stylesheets/ # CSS styles
 ```
 
 ## Writing Documentation
 
-### Markdown Support
-
-The documentation uses [MyST Parser](https://myst-parser.readthedocs.io/) to support Markdown format. You can write documentation directly in Markdown, with support for the following extensions:
-
-- Code block fences (using `:colon_fence:`)
-- Definition lists
-- Task lists
-- Math formulas (using `$` or `$$`)
-- Substitutions and references
-- And more
-
-### Adding New Documentation
-
-1. Create a `.md` file in the appropriate directory
-2. Add the corresponding entry in `index.rst`
+- All documentation is written in Markdown
+- Use [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/) extensions
+- Admonitions, code blocks with copy button, and Mermaid diagrams are supported
 
-For example, to add a new user guide:
-
-```rst
-.. toctree::
-   :maxdepth: 2
-   :caption: User Guide
-
-   user-guide/sql-analytics
-   user-guide/memory-analysis
-   user-guide/new-guide  # Newly added documentation
-```
-
-### Documentation Format Examples
+### Example Admonition
 
 ```markdown
-# Title
-
-This is a paragraph of regular text.
-
-## Code Example
-
-```python
-def hello():
-    print("Hello, World!")
-```
-
-## Admonitions
-
-```{note}
-This is a note.
-```
-
-```{warning}
-This is a warning.
-```
-
-## Math Formulas
-
-Inline formula: $E = mc^2$
+!!! note "Title"
+    This is a note admonition.
 
-Block formula:
-
-$$
-\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
-$$
+!!! warning
+    This is a warning.
 ```
 
-## Build Options
-
-### HTML Output
+### Example Mermaid Diagram
 
-```bash
-make html
+````markdown
+```mermaid
+graph LR
+    A[Start] --> B[Process]
+    B --> C[End]
 ```
+````
 
-### PDF Output (requires LaTeX)
-
-```bash
-make latexpdf
-```
+## Deployment
 
-### Other Formats
+To deploy to GitHub Pages:
 
 ```bash
-make help  # View all available formats
+make deploy
 ```
-
-## Theme and Styling
-
-The documentation uses the `sphinx_rtd_theme` (Read the Docs theme). You can modify the theme configuration in `conf.py`.
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Module not found error**
-   - Ensure all dependencies are installed: `pip install -r requirements_doc.txt`
-
-2. **Build failure**
-   - Check for syntax errors in the documentation
-   - Ensure all referenced files exist
-
-3. **Character encoding issues**
-   - Ensure documentation uses UTF-8 encoding
-   - Check language settings in `conf.py`
-
-## More Information
-
-- [Sphinx Documentation](https://www.sphinx-doc.org/)
-- [MyST Parser Documentation](https://myst-parser.readthedocs.io/)
-- [Read the Docs Theme Documentation](https://sphinx-rtd-theme.readthedocs.io/)