DISC: deprecate notebook parameter in to_html()

[simonjayhawkins]

should to_html(notebook=True) be part of the public facing API or called just from repr_html()?

[WillAyd]

This is already documented in the API in development:

http://pandas-docs.github.io/pandas-docs-travis/generated/pandas.DataFrame.to_html.html?highlight=to_html

I'm not clear by the issue if you are asking whether it should be documented or deprecated altogether, though I would be -1 on deprecation (clarification would be helpful).

[simonjayhawkins]

i'm not au fait with the deprecation process, hence opened an issue to start a discussion.

i assume that if deprecation is agreed then a deprecation warning is issued in the next release and the change is not made for a couple of releases. I hadn't thought about just removing it from the documentation... that could be a good start.

personally, I don't think it's necessary from a user perspective (i.e from df.to_html()) and hence removing it would simplify the API.

from a code perspective, i'm looking to make HTMLFormatter a subclass of DataFrameFormatter instead of passing the DataFrameFormatter object to the HTMLFormatter on instantiation.

This could naturally evolve in time with enhancements and feature requests into separate subclasses of HTMLFormatter.. say NotebookFormatter and ToHTMLFormatter. Having the notebook parameter in to_html() would not prevent this, just make it less straightforward.

[WillAyd]

I'll admit I'm not terribly familiar with this parameter nor its usage. If you have a code cleanup in mind though I suppose a PR is the best way to go about it unless one of the other core devs objects to the possibility of deprecation here.

To answer your question about deprecation, yes we typically issue a FutureWarning for deprecated parameters and do the actual removal a few releases later. You can find other examples of these in closed PRs using the Deprecate label

[simonjayhawkins]

If you have a code cleanup in mind though I suppose a PR is the best way to go about it unless one of the other core devs objects to the possibility of deprecation here.

i'll aim to put a draft PR together for the deprecation shortly.

I'd like to have a base class for to_html that is shared with NotebookFormatter rather than the current situation where HTMLFormatter is the base class of NotebookFormatter.

Having notebook parameter in to_html() method effectively means that all the functionality of to_html has to be available with notebook=True option and limits divergence in functionality.

[jorisvandenbossche]

@simonjayhawkins if I am correct, what the notebook argument does is adding some styling so it renders nicely in a notebook?
This could in principle be useful for users as well? (eg to create html to then paste into a notebook markdown cell)

[simonjayhawkins]

@simonjayhawkins if I am correct, what the notebook argument does is adding some styling so it renders nicely in a notebook?

It just adds a <div> and some style.

       # We use the "scoped" attribute here so that the desired
       # style properties for the data frame are not then applied
       # throughout the entire notebook.

This could in principle be useful for users as well? (eg to create html to then paste into a notebook markdown cell)

Yes. to_markdown() would be better.

a couple of issues.

1. At the moment there is not a clear separation between the display in the notebook (repr) and HTML as an output format (io). Display options bleed into the to_html() as an output format.
2. Many permutations of to_html() parameters are not tested with notebook=True. Only parameters relevant to the notebook _repr_html_ are tested. IMO the implementation of the notebook argument of to_html() as an output format is incomplete.

Both these issues could still be addressed without deprecating the notebook argument.

The first was effectively started with this PR. It is necessary to dispatch to DataFrameFormatter directly instead of calling to_html.

The second requires additional tests and a clean implementation of the application of display options.