mika-data opened a new issue, #58094: URL: https://github.com/apache/spark/issues/58094
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. <img width="1010" height="469" alt="Image" src="https://github.com/user-attachments/assets/c63a22bc-0e7a-45a6-bd65-c2463b9c294b"; /> 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 <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><key></code>.</p></td> </tr> </table> </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: ```html 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](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 <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: ```html <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><numResults></code> must be between <code><min></code> and <code><max></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.</p></td> </tr> </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](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 <img width="391" height="160" alt="Image" src="https://github.com/user-attachments/assets/cc6fa122-898f-43b5-b176-516085f52c49"; /> 1.1.B <img width="387" height="159" alt="Image" src="https://github.com/user-attachments/assets/51eb486e-83eb-4089-ae8c-4cbef2a818b7"; /> 1.2.B <img width="393" height="158" alt="Image" src="https://github.com/user-attachments/assets/8fb1c154-2e28-4c25-b6d4-ba1c5b4795fd"; /> 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. <img width="721" height="529" alt="Image" src="https://github.com/user-attachments/assets/33ef0c02-ed98-49bc-8b6a-1300d15ac0c8"; /> This seems to happen, in every row, where there is no number in the first table column SQLSTATE. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
