kubeflow / kubeflow/sdk

docs: add module-level docstrings to package __init__ files

Open
#644 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
148
Forks
262
Avg merge
1d 2h
Merged PRs (30d)
1

Description

## Summary

Many package `__init__.py` files in the SDK either have no module docstring or only a short one-liner. Adding brief module-level docstrings would make the package layout easier to navigate in IDEs, `help()`, and generated API docs.

## Proposed changes

Add concise module docstrings to the public package `__init__.py` files under:

- `kubeflow/`
- `kubeflow/common/`
- `kubeflow/hub/` and `kubeflow/hub/api/`
- `kubeflow/optimizer/` (including `api/`, `backends/`, `constants/`, `types/`)
- `kubeflow/spark/` (including `api/`, `backends/`)
- `kubeflow/trainer/` (including `api/`, `backends/`, `constants/`, `types/`)

Also add missing `__init__.py` files where needed for package completeness (for example under `trainer/backends/container/` and `trainer/backends/container/adapters/` if those packages are importable but currently lack them).

## Scope

- Documentation only: module docstrings in `__init__.py` files
- No functional code changes
- No new architecture overview document in this issue

## Example style

```python
"""Execution backends for the Kubeflow Trainer.

Includes Kubernetes, container (Docker/Podman), and local process backends.
"""
```

Keep them short: what the package is for, and the main pieces it exposes.

## Why

Module docstrings are the first thing developers see when inspecting a package. Filling them in makes the SDK structure clearer without changing runtime behavior.

Contributor guide

Open the contributing guide

Research direction

Inventory the public __init__.py files under kubeflow/, kubeflow/common/, hub/, optimizer/, spark/, and trainer/, including the listed subpackages; inspect existing docstring style before editing. Add concise purpose-and-contents docstrings and any missing package files, including the noted trainer container paths. Done means all in-scope public packages have consistent module documentation with no functional changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
74/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.