Skip to content

docs: improve documentation for input/output types#2864

Open
markphelps wants to merge 4 commits intomainfrom
docs/improve-input-output-types
Open

docs: improve documentation for input/output types#2864
markphelps wants to merge 4 commits intomainfrom
docs/improve-input-output-types

Conversation

@markphelps
Copy link
Contributor

@markphelps markphelps commented Mar 25, 2026

Summary

  • Expands docs/python.md input/output type documentation into a complete reference with examples and limitations
  • Regenerates docs/llms.txt
  • Adds repository-wide Markdown linting via markdownlint-cli2 in mise and CI

Fixes #2854

Documentation updates (docs/python.md)

  • Rewrites the Input and output types section from a short bullet list into structured reference docs
  • Adds a primitive type table with JSON Schema mappings
  • Documents wrapper/container usage and examples for:
    • Optional[T] and T | None
    • list[T] (input and output)
    • dict (opaque JSON object)
  • Adds structured output coverage for:
    • cog.BaseModel
    • Pydantic v2 BaseModel
    • supported BaseModel field types
  • Adds explicit type limitations (e.g. nested generics and unsupported unions)
  • Corrects prior inaccuracies:
    • AsyncIterator should be imported from typing (not cog)
    • output model class is not required to be named Output
    • clarifies os.PathLike compatibility notes

Markdown linting/tooling updates

  • Adds markdownlint-cli2 as a mise-managed tool (npm:markdownlint-cli2)
  • Adds .markdownlint-cli2.yaml with scoped baseline rules and excludes
  • Adds/updates mise tasks:
    • lint:docs, lint:docs:fix
    • fmt:docs, fmt:docs:fix now run markdownlint-cli2
    • includes docs linting in aggregate lint and lint:fix
  • Updates CI workflow to:
    • detect docs changes for any *.md file
    • run a dedicated lint-docs job
    • include lint-docs in the final ci-complete gate
  • Applies small markdown autofixes (trailing whitespace) in existing markdown files touched by --fix

Rewrite the Input and output types section in docs/python.md to
comprehensively document all supported types, wrapper types, and
structured output patterns.

Changes:
- Add primitive types reference table with JSON Schema mappings
- Document dict as input/output type
- Document Optional with both Optional[T] and T | None syntax
- Document list as both input and output type with examples
- Add structured output section covering cog.BaseModel and Pydantic BaseModel
- Add BaseModel field types reference table
- Add type limitations section (nested generics, unions, etc.)
- Fix AsyncIterator import (use typing.AsyncIterator, not cog)
- Remove incorrect claim that output class must be named Output
- Note that os.PathLike subclasses are accepted as cog.Path
- Regenerate docs/llms.txt
@markphelps markphelps marked this pull request as ready for review March 25, 2026 14:41
@markphelps markphelps requested a review from a team as a code owner March 25, 2026 14:41
@markphelps markphelps requested a review from michaeldwan March 25, 2026 14:41
Enforce baseline Markdown hygiene across tracked docs with markdownlint tasks and a CI gate, while keeping rule scope narrow to avoid broad formatting churn.
@markphelps markphelps enabled auto-merge March 25, 2026 15:48
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.

Improve docs for input/output types

1 participant