Skip to content

Commit d352ce8

Browse files
safurrierclaude
safurrier
and
claude
authored
feat: Add optional MkDocs documentation setup with Material theme (#4)
* feat: Add optional MkDocs documentation setup with Material theme ## Summary Add comprehensive MkDocs documentation system that integrates seamlessly with the `make init` process as an optional (default-on) feature. ## Features - **Optional Integration**: Prompted during `make init` with default "yes" - **Generic Templates**: Placeholder-based templates that generate project-specific docs - **Complete Setup**: MkDocs + Material theme + mkdocstrings + GitHub Pages deployment - **Template Documentation**: Current docs explain how to use the template itself - **Generated Documentation**: Created docs describe the specific project being built ## Implementation ### Template System - `templates/` directory with placeholder-based files (`{project_name}`, `{author_name}`, etc.) - Templates for: mkdocs.yml, docs structure, GitHub Actions workflow - Auto-generation during `make init` based on user inputs ### Integration Points - Added to `scripts/init_project.py` as optional step after example code choice - Makefile targets for docs operations (build, serve, check, clean) - Conditional tests that work with or without docs enabled - GitHub Actions workflow for automated deployment ### User Experience ```bash make init # → Project name, description, author (existing flow) # → Documentation setup? (Y/n) [y] ← NEW optional step # → Creates fully customized documentation for the project ``` ## Technical Details - Uses proven patterns from working MkDocs setups - Integrates with existing uv-based dependency management - Follows project's quality standards (tests, linting, type checking) - Maintains backward compatibility for projects that skip docs ## Benefits 1. **Professional Documentation**: Every project can have beautiful, searchable docs 2. **Low Maintenance**: Auto-generated API docs + simple content structure 3. **GitHub Pages Ready**: Automatic deployment on main branch pushes 4. **Developer Friendly**: Local development server with hot reload 5. **Template Evolution**: Documentation setup improves as template updates 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Fix documentation setup bugs in init script - Fix os.makedirs error when output_path has no parent directory - Fix docs_choice variable scope issue by using docs_enabled flag - Clarify example code prompt to show (1/2/3) for clearer default indication These fixes address issues discovered during UX testing of the documentation setup flow. --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2f07b8d commit d352ce8

18 files changed

Lines changed: 2148 additions & 13 deletions

‎.github/workflows/docs.yml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- 'mkdocs.yml'
10+
- '.github/workflows/docs.yml'
11+
pull_request:
12+
branches:
13+
- main
14+
paths:
15+
- 'docs/**'
16+
- 'mkdocs.yml'
17+
18+
permissions:
19+
contents: write
20+
21+
jobs:
22+
deploy:
23+
runs-on: ubuntu-latest
24+
if: github.event_name == 'push'
25+
26+
steps:
27+
- uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0
30+
31+
- name: Configure Git Credentials
32+
run: |
33+
git config user.name github-actions[bot]
34+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
35+
36+
- uses: actions/setup-python@v5
37+
with:
38+
python-version: 3.x
39+
40+
- name: Install uv
41+
run: pip install uv
42+
43+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
44+
45+
- uses: actions/cache@v4
46+
with:
47+
key: mkdocs-material-${{ env.cache_id }}
48+
path: .cache
49+
restore-keys: |
50+
mkdocs-material-
51+
52+
- name: Install dependencies
53+
run: uv sync --group dev
54+
55+
- name: Deploy documentation
56+
run: uv run mkdocs gh-deploy --force
57+
58+
build-check:
59+
runs-on: ubuntu-latest
60+
if: github.event_name == 'pull_request'
61+
62+
steps:
63+
- uses: actions/checkout@v4
64+
65+
- uses: actions/setup-python@v5
66+
with:
67+
python-version: 3.x
68+
69+
- name: Install uv
70+
run: pip install uv
71+
72+
- name: Install dependencies
73+
run: uv sync --group dev
74+
75+
- name: Build documentation
76+
run: uv run mkdocs build --strict
77+
78+
- name: Check build output
79+
run: |
80+
echo "✅ Documentation builds successfully"
81+
echo "📊 Site size: $(du -sh site/ | cut -f1)"
82+
echo "📄 Pages built: $(find site/ -name "*.html" | wc -l)"

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,7 @@ docker/.env
1616
.ruff_cache/*
1717
.aider*
1818
CLAUDE.md
19+
20+
# Documentation build artifacts
21+
site/
22+
.cache/

‎Makefile‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: compile-deps setup clean-pyc clean-test clean-venv clean test mypy lint format check clean-example dev-env refresh-containers rebuild-images build-image push-image
1+
.PHONY: compile-deps setup clean-pyc clean-test clean-venv clean test mypy lint format check clean-example docs-install docs-build docs-serve docs-check docs-clean dev-env refresh-containers rebuild-images build-image push-image
22

33
# Module name - will be updated by init script
44
MODULE_NAME := src
@@ -62,6 +62,55 @@ format: setup # Run ruff formatter
6262

6363
check: setup lint format test mypy # Run all quality checks
6464

65+
# Documentation
66+
###############
67+
DOCS_PORT ?= 8000
68+
69+
docs-install: setup ## Install documentation dependencies
70+
@echo "Installing documentation dependencies..."
71+
uv sync --group dev
72+
@echo "Documentation dependencies installed"
73+
74+
docs-build: docs-install ## Build documentation site
75+
@echo "Building documentation..."
76+
uv run mkdocs build --strict
77+
@echo "Documentation built successfully"
78+
@echo "📄 Site location: site/"
79+
@echo "🌐 Open site/index.html in your browser to view"
80+
81+
docs-serve: docs-install ## Serve documentation locally with live reload
82+
@echo "Starting documentation server with live reload..."
83+
@echo "📍 Documentation will be available at:"
84+
@echo " - Local: http://localhost:$(DOCS_PORT)"
85+
@echo "🔄 Changes will auto-reload (press Ctrl+C to stop)"
86+
@echo ""
87+
@echo "💡 To use a different port: make docs-serve DOCS_PORT=9999"
88+
uv run mkdocs serve --dev-addr 0.0.0.0:$(DOCS_PORT)
89+
90+
docs-check: docs-build ## Check documentation build and links
91+
@echo "Checking documentation..."
92+
@echo "📊 Site size: $$(du -sh site/ | cut -f1)"
93+
@echo "📄 Pages built: $$(find site/ -name "*.html" | wc -l)"
94+
@echo "🔗 Checking for common issues..."
95+
@if grep -r "404" site/ >/dev/null 2>&1; then \
96+
echo "⚠️ Found potential 404 errors"; \
97+
else \
98+
echo "✅ No obvious 404 errors found"; \
99+
fi
100+
@if find site/ -name "*.html" -size 0 | grep -q .; then \
101+
echo "⚠️ Found empty HTML files"; \
102+
find site/ -name "*.html" -size 0; \
103+
else \
104+
echo "✅ No empty HTML files found"; \
105+
fi
106+
@echo "Documentation check complete"
107+
108+
docs-clean: ## Clean documentation build files
109+
@echo "Cleaning documentation build files..."
110+
rm -rf site/
111+
rm -rf .cache/
112+
@echo "Documentation cleaned"
113+
65114
# Project Management
66115
##################
67116
clean-example: # Remove example code (use this to start your own project)

‎docs/getting-started.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Getting Started with Python Collab Template
2+
3+
This guide walks you through using this template to create a new Python project.
4+
5+
## Prerequisites
6+
7+
- Python 3.9 or higher
8+
- Git
9+
- GitHub account (for template usage)
10+
11+
## Creating a Project from This Template
12+
13+
### Step 1: Create Repository from Template
14+
15+
1. Go to this template repository on GitHub
16+
2. Click **"Use this template"** button
17+
3. Choose **"Create a new repository"**
18+
4. Fill in your repository details:
19+
- Repository name (e.g., `my-awesome-project`)
20+
- Description
21+
- Public/Private visibility
22+
23+
### Step 2: Clone and Initialize
24+
25+
1. Clone your new repository:
26+
```bash
27+
git clone https://github.com/your-username/your-project-name.git
28+
cd your-project-name
29+
```
30+
31+
2. Initialize your project:
32+
```bash
33+
make init
34+
```
35+
36+
3. Follow the interactive prompts:
37+
- **Project name**: Enter your project name (e.g., "My Awesome Project")
38+
- **Description**: Brief description of your project
39+
- **Author info**: Your name and email (auto-detected from git config)
40+
- **Example code**: Choose how to handle example code:
41+
- Keep (useful for reference)
42+
- Minimal (basic working example)
43+
- Remove (clean slate)
44+
- **Documentation**: Set up MkDocs documentation (default: yes)
45+
- **Pre-commit hooks**: Enable quality checks on commit (default: yes)
46+
47+
### Step 3: Verify Setup
48+
49+
After initialization, verify everything works:
50+
51+
```bash
52+
# Run all quality checks
53+
make check
54+
55+
# If you enabled documentation
56+
make docs-serve
57+
```
58+
59+
## Project Structure After Initialization
60+
61+
Your initialized project will have:
62+
63+
```
64+
your-project-name/
65+
├── your_project_name/ # Main package (renamed from src/)
66+
├── tests/ # Test files
67+
├── docs/ # Documentation (if enabled)
68+
├── .github/workflows/ # CI/CD workflows
69+
├── pyproject.toml # Project configuration
70+
├── Makefile # Development commands
71+
└── README.md # Project documentation
72+
```
73+
74+
## Development Workflow
75+
76+
### Daily Development
77+
78+
1. Make your changes to the code
79+
2. Add or update tests
80+
3. Run quality checks:
81+
```bash
82+
make check
83+
```
84+
4. Update documentation if needed
85+
5. Commit and push
86+
87+
### Available Commands
88+
89+
Your project comes with these make targets:
90+
91+
- `make setup` - Set up development environment
92+
- `make test` - Run tests with coverage
93+
- `make lint` - Run linting with auto-fix
94+
- `make format` - Format code
95+
- `make mypy` - Run type checking
96+
- `make check` - Run all quality checks
97+
- `make docs-serve` - Serve documentation locally (if enabled)
98+
- `make docs-build` - Build documentation (if enabled)
99+
- `make docs-check` - Validate documentation build (if enabled)
100+
101+
### Documentation (If Enabled)
102+
103+
If you chose to set up documentation:
104+
105+
1. **Local development**:
106+
```bash
107+
make docs-serve
108+
# Visit http://localhost:8000
109+
```
110+
111+
2. **Content organization**:
112+
- `docs/index.md` - Project homepage
113+
- `docs/getting-started.md` - User guide
114+
- `docs/reference/api.md` - Auto-generated API docs
115+
116+
3. **GitHub Pages setup**:
117+
- Go to repository Settings → Pages
118+
- Set source to "GitHub Actions"
119+
- Documentation will auto-deploy on main branch pushes
120+
121+
### CI/CD
122+
123+
Your project includes GitHub Actions workflows:
124+
125+
- **Quality checks** (`tests.yml`): Runs on PRs and pushes
126+
- **Documentation** (`docs.yml`): Deploys docs to GitHub Pages (if enabled)
127+
128+
## Next Steps
129+
130+
1. **Update README.md** with project-specific information
131+
2. **Add your code** in the main package directory
132+
3. **Write tests** for your functionality
133+
4. **Update documentation** to describe your project
134+
5. **Set up GitHub Pages** (if documentation enabled)
135+
6. **Configure repository settings** (branch protection, etc.)
136+
137+
## Tips
138+
139+
- The template includes example code you can reference or remove
140+
- All configuration follows modern Python best practices
141+
- The documentation system auto-generates API docs from docstrings
142+
- Pre-commit hooks ensure code quality before commits
143+
- Use `make` commands for consistent development workflow

‎docs/index.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Python Collab Template
2+
3+
A modern, collaborative Python project template with comprehensive tooling and best practices built-in.
4+
5+
## 🎯 Template Features
6+
7+
This template provides everything you need for a professional Python project:
8+
9+
- 🔧 **Modern Tooling**: UV package manager, Ruff formatting/linting, MyPy type checking
10+
- 🧪 **Testing**: pytest with coverage reporting and CI integration
11+
- 📚 **Documentation**: Optional MkDocs + Material theme with auto-generation
12+
- 🚀 **CI/CD**: GitHub Actions with quality checks and automated deployment
13+
- 🐳 **Development**: Docker support and pre-commit hooks
14+
- 📦 **Packaging**: Modern pyproject.toml configuration with hatchling
15+
16+
## 🚀 Quick Start
17+
18+
### Using This Template
19+
20+
1. **Create a new repository** from this template on GitHub
21+
2. **Clone your new repository**:
22+
```bash
23+
git clone https://github.com/your-username/your-project-name.git
24+
cd your-project-name
25+
```
26+
3. **Initialize your project**:
27+
```bash
28+
make init
29+
```
30+
4. **Follow the prompts** to customize your project
31+
32+
### What `make init` Does
33+
34+
The initialization script will:
35+
- Prompt for project name, description, and author information
36+
- Update all configuration files with your project details
37+
- Choose how to handle example code (keep, simplify, or remove)
38+
- Optionally set up MkDocs documentation (default: yes)
39+
- Rename directories and update imports
40+
- Set up git repository and pre-commit hooks
41+
42+
## 📁 Template Structure
43+
44+
```
45+
python-collab-template/
46+
├── src/ # Source code (renamed during init)
47+
├── tests/ # Test files
48+
├── scripts/ # Utility scripts (including init)
49+
├── templates/ # Documentation templates
50+
├── docker/ # Docker configuration
51+
├── .github/workflows/ # CI/CD automation
52+
├── pyproject.toml # Project configuration
53+
├── Makefile # Development commands
54+
└── README.md # Project documentation
55+
```
56+
57+
## 🛠️ Available Commands
58+
59+
After initialization, your project will have these commands:
60+
61+
- `make setup` - Set up development environment
62+
- `make test` - Run tests with coverage
63+
- `make check` - Run all quality checks
64+
- `make docs-serve` - Serve documentation locally (if enabled)
65+
- `make docs-build` - Build documentation (if enabled)
66+
67+
For complete usage instructions, see the [Getting Started](getting-started.md) guide.

‎docs/reference/api.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# API Reference
2+
3+
This page contains the auto-generated API documentation for the project.
4+
5+
::: src
6+
options:
7+
show_root_heading: true
8+
members_order: source
9+
show_source: false

0 commit comments

Comments
 (0)