[SPARK-3909][PySpark][Doc] A corrupted format in Sphinx documents and building warnings

[cocoatomo]

Sphinx documents contains a corrupted ReST format and have some warnings.

The purpose of this issue is same as https://issues.apache.org/jira/browse/SPARK-3773.

commit: 0e8203f

output

$ cd ./python/docs
$ make clean html
rm -rf _build/*
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.2.3
loading pickled environment... not yet created
building [html]: targets for 4 source files that are out of date
updating environment: 4 added, 0 changed, 0 removed
reading sources... [100%] pyspark.sql                                                                                                                                                                     
/Users/<user>/MyRepos/Scala/spark/python/pyspark/mllib/feature.py:docstring of pyspark.mllib.feature.Word2VecModel.findSynonyms:4: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/<user>/MyRepos/Scala/spark/python/pyspark/mllib/feature.py:docstring of pyspark.mllib.feature.Word2VecModel.transform:3: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/<user>/MyRepos/Scala/spark/python/pyspark/sql.py:docstring of pyspark.sql:4: WARNING: Bullet list ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] pyspark.sql                                                                                                                                                                      
writing additional files... (12 module code pages) _modules/index search
copying static files... WARNING: html_static_path entry u'/Users/<user>/MyRepos/Scala/spark/python/docs/_static' does not exist
done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 4 warnings.

Build finished. The HTML pages are in _build/html.

[SparkQA]

QA tests have started for PR 2766 at commit 2c7faa8.

• This patch merges cleanly.

[SparkQA]

QA tests have finished for PR 2766 at commit 2c7faa8.

• This patch passes all tests.
• This patch merges cleanly.
• This patch adds no public classes.

[AmplabJenkins]

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/SparkPullRequestBuilder/21643/Test PASSed.

[JoshRosen]

This looks good to me; thanks! I'm happy to merge this PR, but I fear that we're going to continue this cycle of re-introducing and fixing doctest / Sphinx problems until we have Jenkins configured to automatically test the docs. As a short-term fix, I'll make sure to test the docs for compilation errors before cutting new Spark release candidates.

[cocoatomo]

Thank you for the comment.
I'm also happy that Jenkins checks this kind of issue rather than me.

-W option of sphinx-build would help us to check and report errors strictly.

http://sphinx-doc.org/invocation.html#cmdoption-sphinx-build-W

It is used through a make command such like:

$ SPHINXOPTS=-W make clean html