kubeflow / kubeflow/sdk

Fix remaining Sphinx warnings in Spark API documentation

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

Description

### What is the issue?

As a follow-up to PR #738, there are a few remaining Sphinx `docutils` warnings generated when running `make docs` locally.

To keep the previous PR focused, I am opening this separate issue to track and resolve these remaining formatting warnings across the SDK modules.

### Details of the warnings

When running the Sphinx build, the following actionable warnings are triggered from within the `kubeflow/sdk` source tree:

**Spark Module:**
`kubeflow/spark/api/spark_client.py:docstring of kubeflow.spark.api.spark_client.SparkClient.submit_job:6: WARNING: Bullet list ends without a blank line; unexpected unindent. [docutils]`

**Trainer Module:**
`kubeflow/trainer/types/types.py:docstring of kubeflow.trainer.types.types.CustomTrainer:25: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]`
`kubeflow/trainer/types/types.py:docstring of kubeflow.trainer.types.types.CustomTrainerContainer:15: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]`

**Core Docs:**
`docs/source/getting-started/index.rst: WARNING: document isn't included in any toctree [toc.not_included]`

*(Note: The build also outputs some warnings for `pyspark` and `kfp`, but those originate from external packages in the `.venv` rather than the SDK source code, so they are out of scope for this fix).*

### Proposed Solution

1. Fix the unindented bullet list in `spark_client.py`.
2. Fix the unindented block quotes in `CustomTrainer` and `CustomTrainerContainer` in `trainer/types/types.py`.
3. Fix the `toctree` warning for `getting-started/index.rst`.

Contributor guide

Open the contributing guide

Research direction

Run `make docs` to reproduce the listed warnings, then inspect the referenced docstrings in `kubeflow/spark/api/spark_client.py` and `kubeflow/trainer/types/types.py`, plus `docs/source/getting-started/index.rst`. Done means the SDK-source bullet-list, block-quote, and toctree warnings are resolved while external-package warnings remain out of scope.

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
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.