[DOC] HTML Table broken in sql-error-conditions
- 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.
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
1.1.B
1.2.B
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.
This seems to happen, in every row, where there is no number in the first table column SQLSTATE.
Contributor 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