docs: mkdocs-material site with auto-generated command reference#14
Merged
Conversation
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
New documentation site at docs/ powered by Material for MkDocs: - Topic pages: index, installation, OAuth setup, multi-channel profiles, bulk video updates, live broadcasts, comments, analytics, and an API quota cheatsheet. - Auto-generated command reference via an on_pre_build mkdocs hook that runs 'python -m typer ytstudio.main utils docs' so the reference page cannot drift from --help. Generation failures fail the build hard. - Material theme features: navigation tabs + instant nav, light/dark palette toggle, code copy, content tabs, admonitions, Mermaid diagrams via pymdownx.superfences, and Material icons via pymdownx.emoji. CI deploy via .github/workflows/docs.yml: strict build on PRs (no deploy), and 'mkdocs gh-deploy' on push to main (guarded by ref check and concurrency lock so two refs can't race to force-push gh-pages). uv sync uses --locked. pyproject.toml gets a 'docs' dependency group (mkdocs-material, pymdown-extensions, typer-cli). docs/reference.md and site/ are gitignored as build artefacts. Workflow informed by Context7 docs lookup and a Codex review pass. Codex found 2 high (videos and comments command names did not match the real CLI), 4 medium/low (hook fail-soft, missing PR guard on deploy, missing PR build, --locked, missing pymdownx.emoji, analytics quota wording); all applied.
Newer typer (0.26+) no longer pulls click as a runtime dep, which broke tests/test_api.py's 'from click.exceptions import Exit' when the docs group pulled in a typer-cli that bumped typer past the click cutoff. - Switch the test to 'from typer import Exit'; this is what every other caller uses, and typer re-exports Exit for exactly this purpose. - Drop typer-cli from the docs group: 'python -m typer ytstudio.main utils docs' works out of the box on modern typer, no extra package needed.
- Cover videos upload (sidecars, dry-run, --max, resume semantics, quota) on the videos page and surface it in the home highlights and nav label. - Document videos list --scheduled filter. - Replace nonexistent commands in docs: drop ytstudio logout, swap analytics top/by-country/by-day for the real overview/video/query/metrics/dimensions, use comments --status/--sort instead of --moderation-status/--order. - Add videos.insert and thumbnails.set to the API quota cheatsheet. - YouTube-inspired Material palette: black/white primary, red accent, plus an extra.css that pins #FF0033 / #212121 / #FFFFFF on both schemes. - Drop pymdownx.smartsymbols so -- and --- stay as plain hyphens. - check-yaml: pass --unsafe so mkdocs.yml python tags don't trip pre-commit.
jdwit
force-pushed
the
docs/mkdocs-material
branch
from
b84f7c0 to
76aedcf
Compare
- index.md: drop misleading "tags" from the search-replace highlight; the videos search-replace --field flag only accepts title or description, the per-video update command is what handles tags. - comments.md: document that --sort relevance requires --video (YouTube API only honours relevance ordering on a single video). - docs.yml: include src/ytstudio/** in the PR paths filter so CLI surface changes also trigger the strict docs build (the build hook regenerates the command reference from the live typer app).
- center readme top section (ascii.png header, badges, tagline) and remove sections now covered in mkdocs site; add features list and link to docs - site_name -> ytstudio-cli to match package/repo - force youtube-red header/tabs in both schemes (slate's more-specific rule was overriding the var-based default); footer fixed to yt-black - rephrase "what it is" and "why it exists" on landing page; drop multi-channel mention (plumbing, not a headline feature)
switch from mkdocs gh-deploy (gh-pages branch push) to the modern actions/upload-pages-artifact + actions/deploy-pages flow. requires the repo's pages source to be set to "github actions".
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a Material for MkDocs documentation site at `docs/` plus a GitHub Actions workflow that builds on every PR (strict mode) and deploys to `gh-pages` on pushes to `main`.
What is in the site
Workflow
After merge
Enable GitHub Pages in Settings -> Pages with the source set to Deploy from a branch -> gh-pages -> /(root). The first deploy will create that branch.
Review
Built locally with `uv run mkdocs build --strict` (clean) then reviewed by Codex via the rescue subagent. Findings (2 high, 2 medium, 3 low) all applied; the highs were two docs pages documenting commands that did not match the real CLI surface, which is exactly the failure mode the auto-generated reference exists to prevent for the rest.
Test plan