Skip to content

Commit 19d7c9c

Browse files
YosefAshenaficlaude
YosefAshenafi
and
claude
committed
docs: add mkdocs documentation site configuration
Set up mkdocs with Material theme to build documentation site from README files. Includes build and serve scripts for local development and GitHub Actions workflow for automatic GitHub Pages deployment. ## Changes - `mkdocs.yml`: Documentation site configuration with Material theme, custom branding (#0037f0), and navigation matching repository structure - `build-docs.sh`: Script to copy README files and build static site for GitHub Pages - `serve-docs.sh`: Script for local development with automatic README copying and live reload - `.gitignore`: Updated to ignore `docs/` (temporary build folder) and `site/` (generated output) - `.github/workflows/deploy-docs.yml`: GitHub Actions workflow for automatic deployment to GitHub Pages The documentation reads from actual README.md files throughout the repository without duplication. CSS styling will be created dynamically during build. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 7771411 commit 19d7c9c

File tree

5 files changed

+217
-0
lines changed

5 files changed

+217
-0
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Build and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
- main
8+
paths:
9+
- 'README.md'
10+
- '*/README.md'
11+
- 'mkdocs.yml'
12+
- 'docs/**'
13+
- '.github/workflows/deploy-docs.yml'
14+
15+
jobs:
16+
build-and-deploy:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Checkout repository
20+
uses: actions/checkout@v4
21+
22+
- name: Set up Python
23+
uses: actions/setup-python@v4
24+
with:
25+
python-version: '3.11'
26+
27+
- name: Install dependencies
28+
run: |
29+
pip install mkdocs mkdocs-material
30+
31+
- name: Build documentation
32+
run: |
33+
bash build-docs.sh
34+
35+
- name: Deploy to GitHub Pages
36+
uses: peaceiris/actions-gh-pages@v3
37+
with:
38+
github_token: ${{ secrets.GITHUB_TOKEN }}
39+
publish_dir: ./site

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
*.pyc
2+
docs/
3+
site/

‎build-docs.sh‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
#!/bin/bash
2+
# Build script for mkdocs documentation
3+
# This script copies README files into docs/ and builds the site
4+
5+
set -e
6+
7+
echo "Setting up documentation files..."
8+
9+
# Create docs directory
10+
mkdir -p docs
11+
12+
# Copy README files with appropriate names
13+
cp README.md docs/index.md
14+
cp admin/README.md docs/admin.md
15+
cp admintools/README.md docs/admintools.md
16+
cp api/README.md docs/api.md
17+
cp cache/README.md docs/cache.md
18+
cp constants/README.md docs/constants.md
19+
cp decorators/README.md docs/decorators.md
20+
cp extensions/README.md docs/extensions.md
21+
cp forms/README.md docs/forms.md
22+
cp middleware/README.md docs/middleware.md
23+
cp models/README.md docs/models.md
24+
cp utils/README.md docs/utils.md
25+
cp validators/README.md docs/validators.md
26+
cp apps/README.md docs/apps.md
27+
cp lib/README.md docs/lib.md
28+
cp test_scaffold/README.md docs/test_scaffold.md
29+
cp scripts/README.md docs/scripts.md
30+
cp templatetags/README.md docs/templatetags.md
31+
32+
echo "✓ Documentation files copied"
33+
34+
# Build the site
35+
echo "Building documentation site..."
36+
mkdocs build
37+
38+
echo "✓ Documentation built successfully"
39+
echo "✓ Site output is in the 'site/' directory"

‎mkdocs.yml‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
site_name: Django HTK (Hacktoolkit)
2+
site_description: Production-ready Django toolkit with 29 apps, 47+ integrations, and 24 utility categories
3+
site_author: Jonathan Tsai & HTK Contributors
4+
site_url: https://hacktoolkit.github.io/django-htk/
5+
repo_url: https://github.com/hacktoolkit/django-htk
6+
repo_name: django-htk
7+
copyright: Copyright &copy; 2025 HTK Contributors. MIT License.
8+
9+
theme:
10+
name: material
11+
logo: logo.png
12+
palette:
13+
- scheme: default
14+
primary: custom
15+
accent: deep orange
16+
toggle:
17+
icon: material/brightness-7
18+
name: Switch to dark mode
19+
- scheme: slate
20+
primary: custom
21+
accent: deep orange
22+
toggle:
23+
icon: material/brightness-4
24+
name: Switch to light mode
25+
26+
features:
27+
- navigation.instant
28+
- navigation.tracking
29+
- navigation.top
30+
- search.suggest
31+
- search.highlight
32+
- content.code.copy
33+
34+
extra_css:
35+
- extra.css
36+
37+
plugins:
38+
- search
39+
- offline
40+
41+
markdown_extensions:
42+
- admonition
43+
- pymdownx.arithmatex
44+
- pymdownx.betterem:
45+
smart_enable: all
46+
- pymdownx.caret
47+
- pymdownx.critic
48+
- pymdownx.details
49+
- pymdownx.emoji:
50+
emoji_generator: !!python/name:pymdownx.emoji.to_svg
51+
- pymdownx.inlinehilite
52+
- pymdownx.keys
53+
- pymdownx.mark
54+
- pymdownx.smartsymbols
55+
- pymdownx.superfences
56+
- pymdownx.tabbed:
57+
alternate_style: true
58+
- pymdownx.tasklist:
59+
custom_checkbox: true
60+
- pymdownx.tilde
61+
- codehilite
62+
- footnotes
63+
- tables
64+
- toc:
65+
permalink: true
66+
67+
docs_dir: docs
68+
site_dir: site
69+
exclude_docs: |
70+
*.py
71+
__pycache__/
72+
venv/
73+
site/
74+
.git/
75+
.github/
76+
.claude/
77+
.venv/
78+
south_migrations/
79+
migrations/
80+
static/
81+
templates/
82+
__init__.py
83+
84+
nav:
85+
- Home: index.md
86+
- Admin: admin.md
87+
- Admin Tools: admintools.md
88+
- API: api.md
89+
- Cache: cache.md
90+
- Constants: constants.md
91+
- Decorators: decorators.md
92+
- Extensions: extensions.md
93+
- Forms: forms.md
94+
- Middleware: middleware.md
95+
- Models: models.md
96+
- Utils: utils.md
97+
- Validators: validators.md
98+
- Django Apps: apps.md
99+
- Libraries: lib.md
100+
- Test Scaffold: test_scaffold.md
101+
- Scripts: scripts.md
102+
- Template Tags: templatetags.md

‎serve-docs.sh‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
#!/bin/bash
2+
# Serve script for local mkdocs development
3+
# This script copies README files and serves the documentation locally
4+
5+
set -e
6+
7+
echo "Setting up documentation files..."
8+
9+
# Create docs directory
10+
mkdir -p docs
11+
12+
# Copy README files with appropriate names
13+
cp README.md docs/index.md
14+
cp admin/README.md docs/admin.md
15+
cp admintools/README.md docs/admintools.md
16+
cp api/README.md docs/api.md
17+
cp cache/README.md docs/cache.md
18+
cp constants/README.md docs/constants.md
19+
cp decorators/README.md docs/decorators.md
20+
cp extensions/README.md docs/extensions.md
21+
cp forms/README.md docs/forms.md
22+
cp middleware/README.md docs/middleware.md
23+
cp models/README.md docs/models.md
24+
cp utils/README.md docs/utils.md
25+
cp validators/README.md docs/validators.md
26+
cp apps/README.md docs/apps.md
27+
cp lib/README.md docs/lib.md
28+
cp test_scaffold/README.md docs/test_scaffold.md
29+
cp scripts/README.md docs/scripts.md
30+
cp templatetags/README.md docs/templatetags.md
31+
32+
echo "✓ Documentation files copied"
33+
echo ""
34+
echo "Starting mkdocs server..."
35+
mkdocs serve

0 commit comments

Comments
 (0)