Improved module level docstrings

[MarcSkovMadsen]

Addresses a small part of #789 by adding module level docstrings.

The aim here is to provide

• an elevator pitch for hvplot
• a very basic intro and reminder of the api
• info enough to easily navigate hvplot and its resources from the editor.

I believe all the hvplot.pandas, hvplot.xarray, hvplot.ibis needs docstrings that are similar but specialized to the specific data source. These are the entry points for users. Not the top-level hvplot module.

There is one issue though. VS Code does not show docstring tooltips for nested imports like import hvplot.pandas. It only shows for from hvplot import pandas. See microsoft/pylance-release#3093.

[maximlt]

Thanks Marc!

There is one issue though. VS Code does not show docstring tooltips for nested imports like import hvplot.pandas. It only shows for from hvplot import pandas. See microsoft/pylance-release#3093.

Oh I would not advise anyone to make such an import! from hvplot import pandas is confusing as it gives the impression you're importing pandas. Until the Pylance issue is resolved I don't see much point in adding high-level pitch docstring to the modules like pandas.py.

(I think the tests are failing because of the latest xarray)

[MarcSkovMadsen]

Thanks Marc!

There is one issue though. VS Code does not show docstring tooltips for nested imports like import hvplot.pandas. It only shows for from hvplot import pandas. See microsoft/pylance-release#3093.

Oh I would not advise anyone to make such an import! from hvplot import pandas is confusing as it gives the impression you're importing pandas. Until the Pylance issue is resolved I don't see much point in adding high-level pitch docstring to the modules like pandas.py.

(I think the tests are failing because of the latest xarray)

I still see much value :-)

• Modules should have docstrings. Its best practice and helpful.
• It still creates value in Jupyter and VS Code as shown below.
• You have someone willing to contribute the docstrings now, so why not just get them in?

Before

After

If you go to definition you will also find the documentation

[MarcSkovMadsen]

I believe the intro section, how to .. in 3 simple steps and help is the most important sections. I have simplified and removed the rest.

Thanks for the feedback @maximlt . Let me know if there is more I should do? Thanks.

[jbednar]

Looks great; thanks so much!

[maximlt]

Thanks @MarcSkovMadsen for the updates and taking into account my suggestions!

I've just realized that starting from Python 3.7 modules can implement __getattr__ and __dir__ (https://peps.python.org/pep-0562/). This means we could easily get rid of all of the shim modules that were required before with a cleaner approach, and this when hvPlot will require 3.7 as a minimum version (now it's 3.6 but I guess not for too long). This means that the shim module doctsrings, like the one you added in pandas.py, will go away with this new implementation. I'm sorry for the extra work this caused you but I'd suggest you already remove them in this PR? I felt they were anyway very close to the init.py module docstring which I already find very useful!

[MarcSkovMadsen]

I've removed the shim module docstrings @maximlt.

Why do we actually not do hvplot.extension("pandas") or hvplot.extension("xarray") similarly to pn.extension and hv.extension('matplotlib')?

That would be consistent with the rest of the ecosystem and work better with static type checking tools.

[maximlt]

I've removed the shim module docstrings

Thanks!

Why do we actually not do hvplot.extension("pandas") or hvplot.extension("xarray") similarly to pn.extension and hv.extension('matplotlib')?

You can run hvplot.extension('matplotlib') to set the Matplotlib backend, which is consistent with HoloViews. I don't know whether allowing hvplot.extension('pandas') would make it more consistent with the ecosystem. I find hv.extension() and pn.extension() quite confusing, too implicit and possibly overloaded. We see users calling them without really knowing what they do, that might be a documentation issue, I don't know.

work better with static type checking tools.

How?

[maximlt]

I've removed the shim module docstrings @maximlt.

Arf actually I see they're still around. Did you maybe forget to commit?

[MarcSkovMadsen]

I've pushed the changes now @maximlt

[maximlt]

There were still two weird files on your branch. I took the freedom to delete them, they seemed totally unrelated to that PR. Merging, thanks Marc!