Generate API docs from clientele functions?

[phalt]

The idea:

• API servers often use OpenAPI to generate documentation for the API.
• One potential audience for Clientele is API creators who want to ship a client library.
• Those client library maintainers probably don't want to maintain docs for the client lib if they can help it.
• Clientele can use the decorated functions to generate human-readable (and llm-readable) documentation.
• Could probably produce something basic enough for mkdocs or even the brand new Zensical.
• A simple clientele scaffold-docs command could output to a directory with a simple mkdocs.yml, or even just markdown files as a first version.

[phalt]

@peterHoburg your contributions have been brilliant so far, what do you think about this idea?

[peterHoburg]

How am I just now hearing about Zensical?? I love Material for MkDocs!

[peterHoburg]

My first thought would be to focus on making sure clientele is adding all the possible info from OAS 3.1 to the generated code.
[x] Endpoint Docstrings from description
[ ] Schema Docstrings from schema description
[ ] Schema examples
[ ] Other examples?

Then pull that into a doc. Starting with a basic .md file until we figure out the format that works best might be a good idea.
Personally, I like the Go-style docs for "generated from code" documentation.
https://pkg.go.dev/bufio@go1.25.6

Python libs to try that might work out of the box/with setting changes

• pdoc
• Sphinx + autodoc
• MkDocs + mkdocstring

[peterHoburg]

I messed around with mkdocs-material + mkdocstring + griffe-pydanitic and it looks decent!

pyproject.toml deps:

    "griffe-pydantic>=1.0.0",
    "mkdocs-material>=9.6.0",
    "mkdocstrings[python]>=0.29.0",

mkdocs.yml

site_name: example
theme:
  name: material

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          paths: [.]
          options:
            docstring_style: google
            show_source: true
            members_order: source
            show_bases: true
            show_inheritance_diagram: false
            members: true
            inherited_members: false
            filters: ["!^_"]
            separate_signature: true
            show_signature_annotations: true
            extensions:
              - griffe_pydantic:
                  schema: true

nav:
  - Home: index.md
  - API Reference:
    - Client: api/client.md
    - Schemas: api/schemas.md

[peterHoburg]

Unfortunately, I don't think Zensical is ready yet (mkdocstrings is required). When it is I think moving over would be awesome.