Fix how footnote references work in raw HTML tables

[amoeba]

In #108 we combined the bind and ingest tables into one table because we wanted to use rowspan and colspan to improve the display of the combined table. This required using raw HTML since other available table syntaxes can't do rowspan/colspan.

However, raw HTML tables don't support footnote references (i.e., they aren't parsed) so I ended up having to sneak a footnote reference in adbc-drivers/docs.adbc-drivers.org@90dbed3#diff-33b14937b30cc3e495a9d2154282e0ec0e6bbd7b2bd7b6626267895d0004e1cd to get the docs to build correctly.

The solution I came up with won't work long-term because I had to hardcode the id. This ID won't be stable.

We need to come up with a better solution to footnotes for this table, or possibly change the table back into a non-raw-HTML table.

[lidavidm]

I know some Markdown parsers only parse Markdown inside HTML if you have blank lines around the contents of the tag. Does that work? (Others, like Quarto, require using a special attribute on the HTML that contains Markdown.)

Otherwise we could add more custom directives (maybe simple ones corresponding to HTML tags?)

[amoeba]

Interesting. This didn't work,

diff --git a/drivers/bigquery/index.md b/drivers/bigquery/index.md
index f5aec80..01d80d9 100644
--- a/drivers/bigquery/index.md
+++ b/drivers/bigquery/index.md
@@ -266,19 +266,15 @@ Note: The example above is for Python using the [adbc-driver-manager](https://py
   <tr>
     <td>timestamp[us]</td>
     <td style="text-align: center;">DATETIME</td>
-    <td style="text-align: center;">❌ <a class="footnote-reference brackets" href="#id14" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></td>
+    <td style="text-align: center;">
+      ❌
 
+      [^7]
+
+    </td>
   </tr>
 </table>
 
-<!-- Temporary workaround to make this footnote work. MyST doesn't support
-footenotes in HTML tables and also doesn't support Attributes
-(https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#attributes)
-for footnotes but apparently it supports footnotes in raw HTML as long as it's
-not a table.
--->
-<span style="display: none;">[^7]</span>
-
 ## Previous Versions
 
 To see documentation for previous versions of this driver, see the following:

[lidavidm]

Darn.

[lidavidm]

Supposedly CommonMark which MyST implements supports this: https://stackoverflow.com/questions/29368902/how-can-i-wrap-my-markdown-in-an-html-div

So I guess MyST might not.

[lidavidm]

I guess if I get a chance I'll poke at the parser...

[lidavidm]

I poked a bit and it appears HTML tables get treated as literal HTML instead of being recursively parsed. I'm going to guess there's not quite an equivalent set of docutils directives; it could be done but would need work.

It looks like you can use fancy ASCII tables to generate colspan/rowspan: https://stackoverflow.com/questions/53757783/text-wrapping-in-cell-spanning-over-multiple-rows-sphinx-restructuredtext

That would be a pain to generate (I think there are Python packages that can do this, though)

[lidavidm]

@amoeba I fixed it. You have to deindent the HTML, then put the cell contents on their own line. Otherwise it seems the markdown parser assumes you want literal HTML.

This renders the footnote for me:

<table class="docutils data align-default" style="width: 100%;">
<tr>
<th rowspan="2" style="text-align: center; vertical-align: middle;">Arrow Type</th>
<th colspan="2" style="text-align: center;">BigQuery Type</th>
</tr>
<tr>
<th style="text-align: center;">Bind</th>
<th style="text-align: center;">Ingest</th>
</tr>
<tr>
<td>binary</td>
<td colspan="2" style="text-align: center;">BYTES</td>
</tr>
<tr>
<td>bool</td>
<td colspan="2" style="text-align: center;">BOOLEAN</td>
</tr>
<tr>
<td>date32[day]</td>
<td colspan="2" style="text-align: center;">DATE</td>
</tr>
<tr>
<td>decimal128</td>
<td colspan="2" style="text-align: center;">NUMERIC</td>
</tr>
<tr>
<td>float</td>
<td colspan="2" style="text-align: center;">FLOAT64</td>
</tr>
<tr>
<td>double</td>
<td colspan="2" style="text-align: center;">FLOAT64</td>
</tr>
<tr>
<td>int16</td>
<td colspan="2" style="text-align: center;">INT64</td>
</tr>
<tr>
<td>int32</td>
<td colspan="2" style="text-align: center;">INT64</td>
</tr>
<tr>
<td>int64</td>
<td colspan="2" style="text-align: center;">INT64</td>
</tr>
<tr>
<td>string</td>
<td colspan="2" style="text-align: center;">STRING</td>
</tr>
<tr>
<td>time64[us]</td>
<td colspan="2" style="text-align: center;">TIME</td>
</tr>
<tr>
<td>timestamp[us, tz=UTC]</td>
<td colspan="2" style="text-align: center;">TIMESTAMP</td>
</tr>
<tr>
<td>timestamp[us]</td>
<td style="text-align: center;">DATETIME</td>
<td style="text-align: center;">

❌ [^7]

</td>
</tr>
</table>

[amoeba]

That is totally bizarre. Thanks for figuring this out! Did you just look at the myst-parser source?

diff --git a/drivers/bigquery/index.md b/drivers/bigquery/index.md
index f5aec80..8146aa3 100644
--- a/drivers/bigquery/index.md
+++ b/drivers/bigquery/index.md
@@ -266,19 +266,14 @@ Note: The example above is for Python using the [adbc-driver-manager](https://py
   <tr>
     <td>timestamp[us]</td>
     <td style="text-align: center;">DATETIME</td>
-    <td style="text-align: center;">❌ <a class="footnote-reference brackets" href="#id14" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></td>
+<td style="text-align: center;">
 
+❌ [^7]
+
+</td>
   </tr>
 </table>
 
-<!-- Temporary workaround to make this footnote work. MyST doesn't support
-footenotes in HTML tables and also doesn't support Attributes
-(https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#attributes)
-for footnotes but apparently it supports footnotes in raw HTML as long as it's
-not a table.
--->
-<span style="display: none;">[^7]</span>
-
 ## Previous Versions
 
 To see documentation for previous versions of this driver, see the following:

[lidavidm]

@amoeba yes, I added some prints and noticed that the Markdown parser was considering the entire table a "raw" HTML block (so the problem was well before Sphinx actually saw anything)

[amoeba]

Nice, thanks for the help.