attempt to demonstrate usage of plotly as a wrapper, issue #861

[UGuntupalli]

• Closes Add a plotting wrapper that make it easy to get high-quality plots  #861
• I am familiar with the contributing guidelines
• No Tests added
• No Updates entries to docs/sphinx/source/api.rst for API changes.
• Does not Add description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented
  (https://numpydoc.readthedocs.io/en/latest/format.html) compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels and Milestone are assigned to the Pull Request and linked Issue.

[wholmgren]

Thanks for the contribution @UGuntupalli. I think you'll need to add plotly to the setup.py EXTRAS_REQUIRE docs list... see here:

pvlib-python/setup.py

Lines 49 to 50 in 363884d

	'doc': ['ipython', 'matplotlib', 'sphinx == 1.8.5', 'sphinx_rtd_theme',
	'sphinx-gallery'],

Hopefully that will get Readthedocs to render the pull request and we can get a better idea of what we're looking at.

[UGuntupalli]

@wholmgren : Will, please try now, I added plotly to the setup.py section

[wholmgren]

The documentation now builds, but I don't see any plot output on the readthedocs rendering of the page: https://external-builds.readthedocs.io/html/pvlib-python/871/auto_examples/plot_using_plotly_wrapper.html#sphx-glr-auto-examples-plot-using-plotly-wrapper-py

Any ideas? I don't know anything about plotly, sorry.

[kandersolar]

Out of the box, sphinx-gallery only knows how to capture output from a few plotting packages. I think you'll need to configure sphinx to capture ("scrape" in sphinx-gallery lingo) plotly output as well for it to show up in the built documentation. I've never done it, but here's an example: https://github.com/plotly/plotly-sphinx-gallery/blob/master/docs/conf.py#L187-L198

[UGuntupalli]

The dates are not formatted correctly, I still haven't figured that out, but here is the figure to expect

[mikofski]

it might be worth pinging Chris Holdgraf either here on GH or Twitter (handle: choldgraf), I think he has responded to DM's in the past.

[kandersolar]

@UGuntupalli I cloned this branch to my computer and was able to get the docs to build correctly with three changes:

• change test_figure.show() to pio.show(test_figure) in your script
• import the plotly image scraper and set the image_scrapers key in sphinx_gallery_conf in conf.py
• change the examples_dirs key to use os.path.abspath

Details:

diff --git a/docs/examples/plot_using_plotly_wrapper.py b/docs/examples/plot_using_plotly_wrapper.py
index f540b67..2c5e834 100644
--- a/docs/examples/plot_using_plotly_wrapper.py
+++ b/docs/examples/plot_using_plotly_wrapper.py
@@ -107,7 +107,7 @@ y_axis_title = 'Irradiance W/m^2'
 
 test_figure = plot_time_series(input_data=cs, y_axis=['ghi', 'dhi', 'dni'], x_axis='index', title=title,
                                x_axis_title=x_axis_title, y_axis_title=y_axis_title)
-test_figure.show()
+pio.show(test_figure)
 
 
 
diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
index 7e05072..ada0e5a 100644
--- a/docs/sphinx/source/conf.py
+++ b/docs/sphinx/source/conf.py
@@ -333,12 +333,16 @@ ipython_warning_is_error = False
 # https://github.com/pvlib/pvlib-python/issues/837
 suppress_warnings = ['ref.footnote']
 
+from plotly.io._sg_scraper import plotly_sg_scraper
+image_scrapers = ('matplotlib', plotly_sg_scraper,)
+
 # settings for sphinx-gallery
 sphinx_gallery_conf = {
-    'examples_dirs': ['../../examples'],  # location of gallery scripts
+    'examples_dirs': [os.path.abspath('../../examples')],  # location of gallery scripts
     'gallery_dirs': ['auto_examples'],  # location of generated output
     # sphinx-gallery only shows plots from plot_*.py files by default:
     # 'filename_pattern': '*.py',
+    'image_scrapers': image_scrapers
 }
 # supress warnings in gallery output
 # https://sphinx-gallery.github.io/stable/configuration.html

[wholmgren]

+from plotly.io._sg_scraper import plotly_sg_scraper

the name implies that this is a private module - is that right?

This example might be too much of a maintenance burden for pvlib at this time. Perhaps it would be better to create a gist and advertise it on the mailing list.

[kandersolar]

the name implies that this is a private module - is that right?

As far as I've found, _sg_scraper isn't included in the main plotly docs. The only place I've seen it "officially endorsed" is this example repo: https://github.com/plotly/plotly-sphinx-gallery

As far as maintenance burden: I forgot to mention that the scraper also requires conda install -c plotly plotly-orca to work correctly. I'm inclined to agree that (like #856) the output is cool but I think the marginal increase in usefulness over matplotlib doesn't justify the extra effort.

[wholmgren]

Perhaps worth pursuing in the future but I'm going to close for now since I don't see a reasonable way of making this work in the short term.