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
- Fix the unindented bullet list in
spark_client.py.
- Fix the unindented block quotes in
CustomTrainer and CustomTrainerContainer in trainer/types/types.py.
- Fix the
toctree warning for getting-started/index.rst.
What is the issue?
As a follow-up to PR #738, there are a few remaining Sphinx
docutilswarnings generated when runningmake docslocally.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/sdksource 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
pysparkandkfp, but those originate from external packages in the.venvrather than the SDK source code, so they are out of scope for this fix).Proposed Solution
spark_client.py.CustomTrainerandCustomTrainerContainerintrainer/types/types.py.toctreewarning forgetting-started/index.rst.