Add `GT.write_html()` as a helper function for easier HTML output

[jrycw]

Hello team,

I've noticed that some users expect an easier way to interact with our tables. While GT.as_raw_html() is great, it doesn’t fully meet those expectations. To address this, I’d like to propose adding GT.write_html() as a helper function, simplifying the process of writing the table’s HTML directly to a file without needing to use open().

I believe this is a useful addition, and if necessary, we could even rename it to GT._write_html() for unofficial use.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 88.89%. Comparing base (f1c8c94) to head (d32044b).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #485 +/- ## ========================================== + Coverage 88.88% 88.89% +0.01% ========================================== Files 44 44 Lines 5216 5225 +9 ========================================== + Hits 4636 4645 +9 Misses 580 580 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[jrycw]

I've found that utilizing the parameters of GT.as_raw_html() might be a better approach. I suggest we keep the make_page and all_important parameters undocumented, similar to how it's done in GT.as_raw_html().

[machow]

Thanks for this @jrycw -- @rich-iannone and I are pairing on this right now, and thinking about the use of both .as_*() and .write_*() in the Great Tables API.

We noticed that polars .write_*() methods will return a string, if not filename is specified. WDYT of that approach. So in that case, we would deprecate the as_*() methods in favor of write_*() methods.

Basically, it seems like there are 3 possible approaches:

• polars: .write_*() methods return a string when no filename given
• two kinds of methods: each render target has a .as_*() and .write_*() method.
• *polars approach, but with `.as_():** use.as*()instead of.write*()`

Would love to get your input!

[jrycw]

Hello team,

I’m inclined to go with the first option as the higher-level abstraction while retaining .as_*() for internal use.

Here’s my draft implementation below.

[jrycw]

To issue a deprecation message to users, we could take a similar approach to what Polars uses. We might consider decorating as_raw_html() in the GT object, like this:

class GT(GTData):
    ...

    as_raw_html = deprecate_function("Use `GT.write_html()` instead.", version="0.15.0")(as_raw_html) 
    write_html = write_html

This method avoids directly decorating as_raw_html(), which could trigger the message unintentionally when using write_html(). Once we’re ready for full deprecation, we can simply remove the line: as_raw_html = ....