windmill/python-client/DOCS.md

Python Client Documentation

This document describes how the Python client documentation is generated and deployed, similar to the TypeScript client.

Overview

The Python client uses pdoc to automatically generate API documentation from docstrings in the code, similar to how the TypeScript client uses TypeDoc.

Architecture

Following the same pattern as the TypeScript client:

1. Documentation Generator: pdoc (Python) vs TypeDoc (TypeScript)
2. Build Script: build_pdoc.sh (similar to build_typedoc.sh for TS)
3. Output Directory: docs/ containing static HTML
4. Deployment: Copied to /frontend/static/pydocs/ during Docker build
5. URL: Accessible at https://app.windmill.dev/pydocs/wmill.html

Building Documentation

How It Works

The Python client documentation follows the same pattern as the TypeScript client:

1. Docs are checked into git - The docs/ directory is committed to the repository
2. Built during releases - When ./build.sh runs (on releases or manually), it calls ./build_pdoc.sh
3. Copied during Docker build - The Dockerfile copies pre-built docs to the frontend

Locally

To build/update the documentation:

cd /path/to/windmill/python-client
./build_pdoc.sh

This will:

1. Create a virtual environment if needed (.venv/ - gitignored)
2. Install pdoc and dependencies
3. Generate HTML documentation in ./docs/
4. Documentation will be available at file://$(pwd)/docs/wmill.html

After building, you should commit the updated docs:

git add docs/
git commit -m "Update Python client documentation"

In CI/CD

The documentation is built automatically during the release process:

1. On release (pypi_on_release.yml workflow triggers on version tags)
2. Runs ./publish.sh → calls ./build.sh → calls ./build_pdoc.sh
3. Docs are generated and should be committed separately or before the release

In Docker Build

The documentation is copied during Docker build (see Dockerfile line 51):

COPY /python-client/docs/ /frontend/static/pydocs/

This makes the docs available at https://app.windmill.dev/pydocs/ in production.

Documentation Structure

The generated documentation includes:

• Main Module (wmill.html): Overview and module-level functions
• Client Class (wmill/client.html): Full Windmill class API reference
• S3 Types (wmill/s3_types.html): S3 integration types and helpers
• S3 Reader (wmill/s3_reader.html): S3 file reading utilities

All documentation is automatically generated from:

• Function/class docstrings
• Type hints
• Parameter descriptions
• Return type annotations

Writing Good Documentation

To maintain quality documentation:

1. Use clear docstrings following Google or NumPy style:

   def my_function(param1: str, param2: int = 0) -> dict:
       """Short description of function.
   
       Longer description with more details about what the function does
       and any important notes.
   
       Args:
           param1: Description of param1
           param2: Description of param2 (default: 0)
   
       Returns:
           Description of return value
   
       Example:
           >>> result = my_function("test", 5)
           >>> print(result)
           {'status': 'ok'}
       """
   

2. Add type hints - pdoc uses them to generate better documentation

3. Include examples in docstrings where helpful

4. Keep descriptions concise but complete

Comparison with TypeScript Client

Aspect	TypeScript	Python
Generator	TypeDoc	pdoc
Build Script	build_typedoc.sh	build_pdoc.sh
Output Dir	docs/	docs/
Hosted At	/tsdocs/	/pydocs/
Entry Point	modules.html	wmill.html

References

• Windmill Docs: https://windmilldocs/docs/advanced/2_clients/python_client.md
• TypeScript Client Docs: https://app.windmill.dev/tsdocs/modules.html
• Python Client Docs: https://app.windmill.dev/pydocs/wmill.html
• pdoc Documentation: https://pdoc.dev/