mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-05-23 10:19:41 +02:00
Luong NGUYEN
3557d791f5
* feat(scripts): add static website generator from markdown sources (#85) Generate an elegant, mobile-friendly static site from the existing tutorial markdown files. The markdown remains the single source of truth — `scripts/build_website.py` reads from the same `.md` files the EPUB builder uses, rewrites cross-references to site URLs, and rewrites references to non-markdown repo files (`.json`, `.sh`, `.py`) to GitHub blob URLs so users can jump to the source on github.com. Highlights: - Reuses the chapter ordering convention from `build_epub.py` - Anchor algorithm mirrors `check_cross_references.heading_to_anchor` for parity with the validator - Mermaid renders client-side via `mermaid.js` (no pre-render step) - Tailwind CSS via CDN; light/dark theme toggle; sidebar nav; in-page TOC; prev/next page navigation; mobile responsive - 27 unit + smoke tests covering anchors, link rewriting (including `<source srcset>` inside `<picture>`), Mermaid handling, and a full end-to-end build - GitHub Pages deploy workflow at `.github/workflows/pages.yml` Closes #85 * fix(website): use relative URLs in sidebar nav and avoid INDEX.html collision Two bugs found by local browser dogfooding: 1. **Sidebar nav broke from deep pages.** `build_navigation` emitted raw `output_url` values (site-root-relative) which made every sidebar link 404 from any page below the root. Moved the call inside the per-page render loop so each page gets nav links computed relative to its own URL — `01-slash-commands/index.html` from the root, `../01-slash-commands/...` from a depth-1 page, `../../01-slash-commands/...` from depth-2. 2. **`INDEX.md` overwrote `index.html`.** On case-insensitive filesystems (macOS/Windows), `INDEX.html` and `index.html` are the same file, so `INDEX.md` clobbered the rendered `README.md`. Added `_disambiguate_url` that detects case-insensitive collisions and suffixes the colliding page with its source stem (`INDEX-index.html`). Added 2 tests; full suite stays at 83 passed. * fix(scripts): skip URLs with port in localhost/127.0.0.1 skip list `check_links.is_skipped()` did an exact-match comparison against the host, so `http://localhost:8080` (used in scripts/README.md as a preview example) was not skipped and CI's link check tried to fetch it, which fails on the GitHub runner. Strip the port before comparing. * chore(scripts): drop vestigial mypy ignore_errors for build_website The override silenced all mypy errors for build_website, making the "mypy: clean" claim technically vacuous. Removing it shows mypy is actually clean — 0 issues on build_website after type annotations were added during PR review. * feat(website): self-host Tailwind, Mermaid, and Inter fonts Drop all third-party CDN dependencies from rendered pages. The site previously loaded Tailwind from cdn.tailwindcss.com (Play CDN — JIT compile in browser, marked not-for-production), Mermaid from cdn.jsdelivr.net, and Inter/JetBrains Mono from fonts.googleapis.com. Replace with a vendored toolchain: - scripts/vendor_assets.py downloads the Tailwind standalone CLI (Go binary, no Node toolchain), Mermaid's UMD bundle, and Google Fonts CSS + WOFF2 files. Cached under scripts/.vendor-cache/ (gitignored), refetched only when missing. - Tailwind compiles a per-build site/assets/tailwind.css with only the utility classes actually used by the rendered HTML. - Mermaid and font files land in site/assets/vendor/ and load via relative URLs. - Tailwind config + entry CSS live in scripts/website_templates/ alongside the Jinja template. - build_website grows a skip_vendor flag so the smoke test runs offline. - pre-commit mypy hook gets types-Markdown so it can resolve the same imports as the project venv. Verification: 86/86 pytest pass, ruff/mypy/bandit clean, full build produces a working site with zero external requests (verified in a headless browser — no console errors, no failed network calls, Mermaid diagrams render). * fix(website): use tree URLs for repo directory links (#85) * fix(website): include additional top-level docs (#85)
124 lines
3.2 KiB
TOML
124 lines
3.2 KiB
TOML
[project]
|
|
name = "claude-howto"
|
|
version = "1.0.0"
|
|
description = "Claude Code How-To Guide with EPUB builder"
|
|
readme = "README.md"
|
|
license = "MIT"
|
|
requires-python = ">=3.10"
|
|
dependencies = [
|
|
"ebooklib",
|
|
"markdown",
|
|
"beautifulsoup4",
|
|
"httpx",
|
|
"pillow",
|
|
"tenacity",
|
|
"jinja2",
|
|
]
|
|
|
|
[project.optional-dependencies]
|
|
dev = [
|
|
"pytest>=7.0",
|
|
"pytest-asyncio>=0.21",
|
|
]
|
|
|
|
[tool.pytest.ini_options]
|
|
testpaths = ["scripts/tests"]
|
|
asyncio_mode = "auto"
|
|
asyncio_default_fixture_loop_scope = "function"
|
|
python_files = ["test_*.py"]
|
|
python_functions = ["test_*"]
|
|
addopts = "-v"
|
|
|
|
[build-system]
|
|
requires = ["setuptools>=61.0"]
|
|
build-backend = "setuptools.build_meta"
|
|
|
|
[tool.setuptools.packages.find]
|
|
where = ["scripts"]
|
|
include = ["build_epub"]
|
|
exclude = ["tests", "tests.*"]
|
|
|
|
# =============================================================================
|
|
# Ruff Configuration
|
|
# =============================================================================
|
|
[tool.ruff]
|
|
target-version = "py310"
|
|
line-length = 88
|
|
include = ["scripts/**/*.py"]
|
|
exclude = [
|
|
".git",
|
|
".venv",
|
|
"__pycache__",
|
|
".pytest_cache",
|
|
"*.egg-info",
|
|
]
|
|
|
|
[tool.ruff.lint]
|
|
select = [
|
|
"E", # pycodestyle errors
|
|
"W", # pycodestyle warnings
|
|
"F", # Pyflakes
|
|
"I", # isort (import sorting)
|
|
"B", # flake8-bugbear
|
|
"C4", # flake8-comprehensions
|
|
"UP", # pyupgrade
|
|
"SIM", # flake8-simplify
|
|
"TCH", # flake8-type-checking
|
|
"RUF", # Ruff-specific rules
|
|
"PTH", # flake8-use-pathlib
|
|
"PL", # Pylint
|
|
"PERF", # Perflint
|
|
]
|
|
ignore = [
|
|
"E501", # Line too long (handled by formatter)
|
|
"PLR0913", # Too many arguments
|
|
"PLR2004", # Magic value comparison
|
|
"PLR0915", # Too many statements
|
|
"PERF203", # try-except in loop (acceptable for error handling)
|
|
"PERF403", # dict comprehension (readability preference)
|
|
"TC003", # Type-checking imports (not critical)
|
|
"PLC0415", # Import not at top level (acceptable for lazy imports)
|
|
"RUF005", # Collection concatenation (readability preference)
|
|
]
|
|
fixable = ["ALL"]
|
|
unfixable = []
|
|
|
|
[tool.ruff.lint.isort]
|
|
known-first-party = ["build_epub"]
|
|
force-single-line = false
|
|
combine-as-imports = true
|
|
|
|
[tool.ruff.lint.per-file-ignores]
|
|
"scripts/tests/*.py" = ["S101", "PLR2004"]
|
|
|
|
[tool.ruff.format]
|
|
quote-style = "double"
|
|
indent-style = "space"
|
|
skip-magic-trailing-comma = false
|
|
docstring-code-format = true
|
|
|
|
# =============================================================================
|
|
# Bandit Configuration
|
|
# =============================================================================
|
|
# =============================================================================
|
|
# Mypy Configuration
|
|
# =============================================================================
|
|
[tool.mypy]
|
|
python_version = "3.11"
|
|
ignore_missing_imports = true
|
|
no_implicit_optional = true
|
|
warn_unused_ignores = true
|
|
|
|
[[tool.mypy.overrides]]
|
|
module = ["build_epub", "scripts.build_epub"]
|
|
ignore_errors = true
|
|
|
|
[[tool.mypy.overrides]]
|
|
module = ["sync_translations", "scripts.sync_translations"]
|
|
ignore_errors = true
|
|
|
|
[tool.bandit]
|
|
targets = ["scripts"]
|
|
exclude_dirs = ["scripts/tests", ".venv", "__pycache__"]
|
|
skips = ["B101", "B113"] # B113: httpx timeout false positive (timeout is set)
|