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

[mika-data]

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:

<tr id="spark-connect-illegal-state-stream-lifecycle-event-send-after-shutdown">
--
<td></td>
<td class="error-sub-condition">
<span class="error-condition-name">
<code>
<a href="#spark-connect-illegal-state-stream-lifecycle-event-send-after-shutdown">#</a>
</code>
STREAM<wbr />_LIFECYCLE<wbr />_EVENT<wbr />_SEND<wbr />_AFTER<wbr />_SHUTDOWN
</span>
</td>
<td class="error-sub-condition"><p>Cannot send event after shutdown for session <code>&lt;key&gt;</code>.</p></td>
</tr>
&lt;/table&gt;
</numResults></numResults></p></td></tr></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:

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>

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

The JSON snippet for this condition was:

The number of results <numResults> must be between <min> and <max>. Update the literal in 
`APPROX NEAREST <numResults> BY ...` (or `EXACT NEAREST <numResults> BY ...`) to fall within that range.

The HTML code is:

<tr id="nearest-by-join-num-results-out-of-range">
    <td></td>
    <td class="error-sub-condition">
        <span class="error-condition-name">
            <code>
            <a href="#nearest-by-join-num-results-out-of-range">#</a>
            </code>
            NUM<wbr>_RESULTS<wbr>_OUT<wbr>_OF<wbr>_RANGE
        </span>
    </td>
    <td class="error-sub-condition"><p>
The number of results <code>&lt;numResults&gt;</code> must be between <code>&lt;min&gt;</code> and <code>&lt;max&gt;</code>.
Update the literal in <code>APPROX NEAREST</code><numresults><code>BY ...</code> 
(or <code>EXACT NEAREST</code><numresults><code>BY ...</code>) 
to fall within that range.&lt;/p&gt;&lt;/td&gt;
&lt;/tr&gt;
</numresults></numresults></p></td></tr>

As you see, the "tag" <numresults> 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, or
2. repair the JSON to HTML converter in line 25 of docs/_plugins/build-error-docs.py

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.

[szehon-ho]

Nice catch. did you want to submit a pr ?