Fix remaining Sphinx warnings in Spark API documentation
- 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
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