Skip to content

Commit 795d85c

Browse files
ervwalterclaude
ervwalter
and
claude
committed
feat: add GitHub Pages documentation site with MkDocs and llms.txt
Set up MkDocs with Material theme to publish docs/ as an HTML site on GitHub Pages at python-kanka.ewal.dev. Raw markdown files are also served alongside the HTML, and docs/README.md is published as /llms.txt for LLM discoverability. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 6d3b343 commit 795d85c

6 files changed

Lines changed: 430 additions & 2 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [main, master]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v6
22+
23+
- name: Install uv
24+
uses: astral-sh/setup-uv@v7
25+
26+
- name: Set up Python
27+
run: uv python install 3.14
28+
29+
- name: Install docs dependencies
30+
run: uv sync --group docs
31+
32+
- name: Prepare index page
33+
run: mv docs/README.md docs/index.md
34+
35+
- name: Build MkDocs site
36+
run: uv run mkdocs build --strict
37+
38+
- name: Restore README and copy raw markdown to site
39+
run: |
40+
mv docs/index.md docs/README.md
41+
for f in docs/*.md; do
42+
name="$(basename "$f")"
43+
if [ "$name" != "README.md" ]; then
44+
cp "$f" site/
45+
fi
46+
done
47+
cp docs/README.md site/llms.txt
48+
49+
- name: Upload Pages artifact
50+
uses: actions/upload-pages-artifact@v3
51+
with:
52+
path: site/
53+
54+
deploy:
55+
needs: build
56+
runs-on: ubuntu-latest
57+
environment:
58+
name: github-pages
59+
url: ${{ steps.deployment.outputs.page_url }}
60+
steps:
61+
- name: Deploy to GitHub Pages
62+
id: deployment
63+
uses: actions/deploy-pages@v4

‎Makefile‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: install test lint format typecheck check clean coverage help sync build
1+
.PHONY: install test lint format typecheck check clean coverage help sync build docs-serve docs-build
22

33
# Default target
44
help:
@@ -13,6 +13,8 @@ help:
1313
@echo " make clean - Clean up temporary files"
1414
@echo " make coverage - Run tests with coverage report"
1515
@echo " make build - Build the package"
16+
@echo " make docs-serve - Serve docs locally for preview"
17+
@echo " make docs-build - Build docs locally"
1618

1719
# Install development dependencies and sync with lock file
1820
install:
@@ -71,3 +73,22 @@ coverage:
7173
# Build the package
7274
build:
7375
uv build
76+
77+
# Serve docs locally for preview
78+
docs-serve:
79+
mv docs/README.md docs/index.md
80+
uv run mkdocs serve || true
81+
mv docs/index.md docs/README.md
82+
83+
# Build docs locally
84+
docs-build:
85+
mv docs/README.md docs/index.md
86+
uv run mkdocs build --strict
87+
mv docs/index.md docs/README.md
88+
@for f in docs/*.md; do \
89+
name=$$(basename "$$f"); \
90+
if [ "$$name" != "README.md" ]; then \
91+
cp "$$f" site/; \
92+
fi; \
93+
done
94+
cp docs/README.md site/llms.txt

‎docs/CNAME‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
python-kanka.ewal.dev

‎mkdocs.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
site_name: python-kanka
2+
site_url: https://python-kanka.ewal.dev/
3+
site_description: A modern Python client for the Kanka API
4+
repo_url: https://github.com/ervwalter/python-kanka
5+
repo_name: ervwalter/python-kanka
6+
7+
theme:
8+
name: material
9+
features:
10+
- navigation.sections
11+
- navigation.expand
12+
- content.code.copy
13+
- search.suggest
14+
palette:
15+
- scheme: default
16+
primary: indigo
17+
accent: indigo
18+
toggle:
19+
icon: material/brightness-7
20+
name: Switch to dark mode
21+
- scheme: slate
22+
primary: indigo
23+
accent: indigo
24+
toggle:
25+
icon: material/brightness-4
26+
name: Switch to light mode
27+
28+
nav:
29+
- Home: index.md
30+
- Guides:
31+
- Getting Started: getting-started.md
32+
- Core Concepts: core-concepts.md
33+
- Entity CRUD Operations: entities.md
34+
- Entity Types Reference: entity-types-reference.md
35+
- Posts: posts.md
36+
- Search and Filtering: search-and-filtering.md
37+
- Last Sync: last-sync.md
38+
- Pagination: pagination.md
39+
- Assets and Images: assets-and-images.md
40+
- Campaign Gallery: gallery.md
41+
- Error Handling: error-handling.md
42+
- Rate Limiting: rate-limiting.md
43+
- Debug Mode: debug-mode.md
44+
- Known Limitations: known-limitations.md
45+
- Reference:
46+
- API Reference: api-reference.md
47+
48+
markdown_extensions:
49+
- pymdownx.highlight:
50+
anchor_linenums: true
51+
- pymdownx.superfences
52+
- admonition
53+
- tables
54+
- toc:
55+
permalink: true

‎pyproject.toml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,15 @@ dependencies = [
3333

3434
[project.urls]
3535
Homepage = "https://github.com/ervwalter/python-kanka"
36-
Documentation = "https://github.com/ervwalter/python-kanka#readme"
36+
Documentation = "https://python-kanka.ewal.dev/"
3737
Repository = "https://github.com/ervwalter/python-kanka"
3838
Issues = "https://github.com/ervwalter/python-kanka/issues"
3939

4040
[dependency-groups]
41+
docs = [
42+
"mkdocs>=1.6",
43+
"mkdocs-material>=9.5",
44+
]
4145
dev = [
4246
"pytest==9.0.2",
4347
"pytest-asyncio==1.3.0",

0 commit comments

Comments
 (0)