Explore mkdocs alternative

CLAUDE.md

@@ -107,11 +107,25 @@ notebooks/          # Jupyter notebooks
 
 ## Documentation
 
-- Uses **MkDocs** with **Material theme**
-- Configured via `mkdocs.yml`
-- Uses **mkdocstrings** plugin for API documentation from docstrings
-- **Docstring style: NumPy** (not Google)
+### Documentation Philosophy
+
+This template follows a modern approach to documentation:
+
+- **Website documentation** (`docs/`) focuses on **user guides, tutorials, and examples** - the kind of content you can't get in an IDE
+- **API documentation** lives in **docstrings** for IDE consumption - developers see this when coding with autocomplete
+
+Write comprehensive NumPy-style docstrings in the code - these appear in VSCode, PyCharm, and other IDEs when users work with your library. The documentation website teaches users how to use the library through examples and guides.
+
+### Documentation Setup
+
+- Uses **Zensical** (modern static site generator by the Material for MkDocs team)
+- Configured via `mkdocs.yml` (Zensical maintains backward compatibility)
+- Uses `variant: classic` to maintain traditional Material for MkDocs look
+- Simple configuration with no plugins needed
+- **Docstring style: NumPy** (not Google) for IDE display
 - Docstrings should include executable examples that are tested with `make doctest`
+- Build docs with `make docs` or `zensical build`
+- Serve locally with `zensical serve`
 
 ## CI/CD
 
@@ -135,7 +149,7 @@ notebooks/          # Jupyter notebooks
 ## Dependencies
 
 - **Runtime**: numpy
-- **Development**: build, pytest, ruff, mypy, mkdocs, mkdocstrings, mkdocs-material
+- **Development**: build, pytest, ruff, mypy, zensical
 - **Testing**: pytest, pytest-cov, mypy
 - **Notebooks**: jupyter
 

Makefile

@@ -24,7 +24,7 @@ coverage:
 	pytest --cov-report html --cov=$(LIB) tests/
 
 docs: FORCE
-	mkdocs build
+	zensical build
 
 clean:
 	python -c "import shutil; shutil.rmtree('dist', ignore_errors=True)"

docs/index.md

@@ -2,4 +2,4 @@
 
 See more in [Getting started](getting_started.md)
 
-A complete reference is available [here](reference.md)
+Learn how to use the library in the [User Guide](user-guide.md)

docs/user-guide.md

@@ -0,0 +1,37 @@
+# User Guide
+
+This guide shows you how to use the main components in `my_library`. For detailed parameter information and type signatures, refer to the docstrings in your IDE.
+
+## Simulator
+
+The `Simulator` class allows you to sample random numbers within a specified range.
+
+### Basic Usage
+
+```python
+from my_library.simulation import Simulator
+
+# Create a simulator with a name and bounds
+sim = Simulator(name="Scenario1", low=2.0, high=10.0)
+
+# Generate random samples
+samples = sim.simulate(n_samples=100)
+```
+
+### Constructor
+
+```python
+Simulator(name: str, low: float = 0.0, high: float = 1.0)
+```
+
+Creates a new simulator instance with specified bounds.
+
+### Methods
+
+**`simulate(n_samples: int = 1) -> np.ndarray`**
+
+Sample random numbers uniformly distributed between the simulator's low and high bounds.
+
+---
+
+For complete parameter descriptions and examples, see the docstrings in the source code or use your IDE's inline documentation features.

mkdocs.yml

@@ -1,12 +1,5 @@
 site_name: my_library
 
-theme: "material"
-
-plugins:
-- mkdocstrings:
-    handlers:
-      python:
-        options:
-          show_source: false # change this if you prefer to be able to show the source code inside the docs
-          heading_level: 2
-          docstring_style: "numpy" # default is google
+theme:
+  variant: classic
+  name: material

pyproject.toml

@@ -41,9 +41,7 @@ dev = [
   "pytest",
   "ruff",
   "mypy",
-  "mkdocs",
-  "mkdocstrings[python]", 
-  "mkdocs-material"
+  "zensical"
 ]
 
 test= [