apache / apache/spark

[DOC] HTML Table broken in sql-error-conditions

Open
#58,094 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Scala
Stars
44k
Forks
29.4k
PR merge metrics
No merged PRs in 30d

Description

Hello Guys,

This is my first issue here in this project and I have spotted a formatting issue in the generated docs. I want to help.

https://spark.apache.org/docs/latest/sql-error-conditions.html

There is a closing table html tag before the table.

Image

From my investigation, this occures during the generation of the markdown docs/sql-error-conditions.md
The parser finds all not closing html tags, and closes them. Then it closes the table tag and puts the intended closing html table tag at the end.

So the end of the table looks like this in the generated html code:
```html

--



#

STREAM_LIFECYCLE_EVENT_SEND_AFTER_SHUTDOWN

Cannot send event after shutdown for session <key>.

</table>


```

This comes from broken html codes at the following SQL ERROR Conditions:

- NUM_RESULTS_OUT_OF_RANGE
- INVALID_UDF_PARAMETER_PLACEHOLDER_INDEX

The doc generator cannot handle html tags inside of formatted code, as far as I can recognize.
This leads to breaking table structure like in this example:

```html
The number of results must be between and . Update the literal in
APPROX NEARESTBY ... (or EXACT NEARESTBY ...) to fall within that range.


```

Note, the 'APPROX NEARESTBY' and 'EXACT NEARESTBY' are missing a space character and the numResults text.

The [JSON snippet](https://github.com/apache/spark/blob/6f67160ff1787bf9c922f27060025e9bca75a0df/common/utils/src/main/resources/error/error-conditions.json#L6041) for this condition was:
```html
The number of results must be between and . Update the literal in
`APPROX NEAREST BY ...` (or `EXACT NEAREST BY ...`) to fall within that range.
```

The HTML code is:

```html





#

NUM_RESULTS_OUT_OF_RANGE



The number of results <numResults> must be between <min> and <max>.
Update the literal in APPROX NEARESTBY ...
(or EXACT NEARESTBY ...)
to fall within that range.</p></td>
</tr>


```

As you see, the "tag" `````` breaks the surrounding code html snippet.

I would suggest to either

1. avoid html brackets inside the code snippets and use square brackets as it is being used [here](https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-qry-select-nearest-by), or
2. repair the JSON to HTML converter in [line 25](https://github.com/apache/spark/blob/f0c247a4d61436e4daf9cc139d045d14119dca40/docs/_plugins/build-error-docs.py#L25) of docs/_plugins/build-error-docs.py
```python
cleaned_message = re.sub(r"(<.*?>)", lambda x: f"`{x.group(1)}`", message)
```

Solution 1 could look like this:
1.1.A
Image
1.1.B
Image
1.2.B
Image

It has been tested with the doc generator.
A forked branch has not been created yet, because I am not sure, what happens, in execution of these error conditions, when the brackets change.

Furthermore, I noticed, the messages are not all aligned in the same vertical position.

Image

This seems to happen, in every row, where there is no number in the first table column SQLSTATE.

Contributor guide

Open the contributing guide

Research direction

Start with docs/_plugins/build-error-docs.py around line 25 and compare its output for NUM_RESULTS_OUT_OF_RANGE and INVALID_UDF_PARAMETER_PLACEHOLDER_INDEX with common/utils/src/main/resources/error/error-conditions.json. Run the documentation generator and inspect docs/sql-error-conditions.md and the generated HTML. Done means the affected messages preserve literal placeholders and produce valid, correctly structured table rows.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.