This is an automated email from the ASF dual-hosted git repository.
uros-b pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/spark.git
The following commit(s) were added to refs/heads/master by this push:
new d5b467e76059 [SPARK-58348][PYTHON][DOC] Move PySpark error doc header
into global variable
d5b467e76059 is described below
commit d5b467e760598f4c99c1f7ff326c3e0b1e476c17
Author: Nicholas Chammas <[email protected]>
AuthorDate: Sun Aug 2 17:26:55 2026 +0000
[SPARK-58348][PYTHON][DOC] Move PySpark error doc header into global
variable
### What changes were proposed in this pull request?
Move the PySpark error doc header into a global variable and reformat very
long lines.
Tweak the wording of the heading about PySpark errors and exceptions.
### Why are the changes needed?
The lengthy error doc header immediately follows a lengthy method
docstring, leading to a visually confusing mix of indentation levels and
multiline strings. Splitting it up just makes things visually easier to follow.
The wording change of the heading is so it reads more naturally.
### Does this PR introduce _any_ user-facing change?
Documentation only.
### How was this patch tested?
I built and reviewed the PySpark error docs locally.
```sh
cd python/docs
make html
open build/html/development/errors.html
```
### Was this patch authored or co-authored using generative AI tooling?
No.
Closes #57523 from nchammas/python-error-doc-header.
Authored-by: Nicholas Chammas <[email protected]>
Signed-off-by: Uros Bojanic <[email protected]>
---
python/docs/source/development/contributing.rst | 4 +-
python/pyspark/errors_doc_gen.py | 50 +++++++++++++------------
2 files changed, 29 insertions(+), 25 deletions(-)
diff --git a/python/docs/source/development/contributing.rst
b/python/docs/source/development/contributing.rst
index bbf7c49a17d7..d422b69528df 100644
--- a/python/docs/source/development/contributing.rst
+++ b/python/docs/source/development/contributing.rst
@@ -253,8 +253,8 @@ and third block is for another argument. As an example,
please refer `DataFrame.
These blocks should be consistently separated in PySpark doctests, and more
doctests should be added if the coverage of the doctests or the number of
examples to show is not enough.
-Contributing Error and Exception
---------------------------------
+Contributing Errors and Exceptions
+----------------------------------
.. currentmodule:: pyspark.errors
diff --git a/python/pyspark/errors_doc_gen.py b/python/pyspark/errors_doc_gen.py
index c541cd8fb7e2..6cdd376d20cf 100644
--- a/python/pyspark/errors_doc_gen.py
+++ b/python/pyspark/errors_doc_gen.py
@@ -1,26 +1,8 @@
import re
-
from pyspark.errors.error_classes import ERROR_CLASSES_MAP
-
-def generate_errors_doc(output_rst_file_path: str) -> None:
- """
- Generates a reStructuredText (RST) documentation file for PySpark error
classes.
-
- This function fetches error classes defined in
`pyspark.errors.error_classes`
- and writes them into an RST file. The generated RST file provides an
overview
- of common, named error classes returned by PySpark.
-
- Parameters
- ----------
- output_rst_file_path : str
- The file path where the RST documentation will be written.
-
- Notes
- -----
- The generated RST file can be rendered using Sphinx to visualize the
documentation.
- """
- header = """.. Licensed to the Apache Software Foundation (ASF) under one
+_ERROR_DOC_HEADER = """
+.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
@@ -41,12 +23,34 @@ def generate_errors_doc(output_rst_file_path: str) -> None:
Error classes in PySpark
========================
-This is a list of common, named error classes returned by PySpark which are
defined at `error-conditions.json
<https://github.com/apache/spark/blob/master/python/pyspark/errors/error-conditions.json>`_.
+This is a list of common, named error classes returned by PySpark which are
defined at
+`error-conditions.json
<https://github.com/apache/spark/blob/master/python/pyspark/errors/error-conditions.json>`_.
-When writing PySpark errors, developers must use an error class from the list.
If an appropriate error class is not available, add a new one into the list.
For more information, please refer to `Contributing Error and Exception
<contributing.rst#contributing-error-and-exception>`_.
+When writing PySpark errors, developers must use an error class from the list.
If an appropriate
+error class is not available, add a new one into the list. For more
information, please refer to
+`Contributing Errors and Exceptions
<contributing.rst#contributing-errors-and-exceptions>`_.
"""
+
+
+def generate_errors_doc(output_rst_file_path: str) -> None:
+ """
+ Generates a reStructuredText (RST) documentation file for PySpark error
classes.
+
+ This function fetches error classes defined in
`pyspark.errors.error_classes`
+ and writes them into an RST file. The generated RST file provides an
overview
+ of common, named error classes returned by PySpark.
+
+ Parameters
+ ----------
+ output_rst_file_path : str
+ The file path where the RST documentation will be written.
+
+ Notes
+ -----
+ The generated RST file can be rendered using Sphinx to visualize the
documentation.
+ """
with open(output_rst_file_path, "w", encoding="utf-8") as f:
- f.write(header + "\n\n")
+ f.write(_ERROR_DOC_HEADER.strip() + "\n\n")
for error_key, error_details in ERROR_CLASSES_MAP.items():
f.write(error_key + "\n")
# The length of the error class name and underline must be the same
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]