Skip to content

Add documentation site on GitHub Pages - #9

Merged
shrijayan merged 3 commits into
mainfrom
docs-site
Oct 22, 2026
Merged

shrijayan merged 3 commits into
mainfrom
docs-site

Conversation

@shrijayan

@shrijayan shrijayan commented Oct 22, 2026 •

Copy link
Copy Markdown
Owner

Adds a MkDocs Material site for https://shrijayan.github.io/opencode-python-sdk/.

  • Custom palette (paper/ink, amber accent, teal links), Fraunces + IBM Plex Sans + JetBrains Mono, light/dark/auto toggle
  • Hand-built landing page: hero with install command, sync/async tabs with code annotations, feature grid, version chip read from the package
  • Getting started, 10 guides, project pages (how it's built, contributing, versioning, security, changelog)
  • API reference via mkdocstrings: clients, server launcher, every resource, pagination/streams, exceptions, and ~640 types split into domain pages, generated at build time by docs/hooks/types_reference.py
  • llms.txt and llms-full.txt written on build
  • Instant nav, search, copy buttons, social cards (CI), edit-this-page links
  • .github/workflows/docs.yml: mkdocs build --strict on PRs, deploy to Pages on push to main
  • docs dependency group; README, Documentation URL and CONTRIBUTING updated

src/ change is docstring-only: the generator now emits Raises: entries as Name: The server answered <status>. so griffe parses them (regenerated via python -m codegen).

Docs coverage gate

  • tests/test_docs_coverage.py (runs in the existing pytest jobs) fails when a resource/method, opencode.__all__ name or opencode.types model is missing from the reference, when an exported class or its public members lack docstrings, when docs/guides/index.md misses a resource group, or when a guide references a method/type that no longer exists. Failures name the item and the file to edit.
  • Ruff D1 enabled for the published package (it skips _private modules, which the test covers).
  • Codegen now gives sub-resource accessors docstrings; missing docstrings in _exceptions.py and _server.py added.
  • Rule documented in CONTRIBUTING.md.

Landing page, getting started, guides, generated API reference (resources and
~640 types grouped by domain), project pages, llms.txt and llms-full.txt.
Raises sections in generated docstrings now use 'Name: description' so
mkdocstrings parses them.
tests/test_docs_coverage.py checks that every resource, method, export and
type is in the reference, that exported classes have docstrings, that
docs/guides/index.md lists every resource group, and that guides only
reference API that exists. Ruff D1 covers public modules. Adds the missing
docstrings it found and a guide index page.
@shrijayan
shrijayan merged commit be3f514 into main Oct 22, 2026
17 checks passed
@shrijayan
shrijayan deleted the docs-site branch October 22, 2026 09:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant