Python: Port examples to offline

[jonmmease]

There is an ongoing misconception that plotly.py is not (fully) usable without a plot.ly account. As has been discussed before, the documentation is likely partially to blame for this misconception. For example, following along with the documentation for creating a pie chart does require an account (https://plot.ly/python/pie-charts/).

Proposal:

• Rename the top-level "Plotly Fundamentals" documentation group to "Plot.ly Fundamentals", and emphasize that these features are awesome, optional, and require a plot.ly account. Here's where we discuss plotly.plotly.plot, plotly.plotly.iplot, get_figure, etc.
• Port all examples outside of "Plot.ly Fundamentals" to use plotly.offline or FigureWidget rendering approaches.

Thoughts? @jackparmer @chriddyp @cldougl @nicolaskruchten ?

[nicolaskruchten]

I'm on board.

[nicolaskruchten]

The Getting Started page should also be updated to be offline-first: https://plot.ly/python/getting-started/ as should the Cheat Sheet: https://images.plot.ly/plotly-documentation/images/python_cheat_sheet.pdf

[Kully]

@jonmmease

There is an ongoing misconception that plotly.py is not (fully) usable without a plot.ly account.

---

Jon, where are you noticing this misconception the most? Is it through forum posts, word of mouth, conferences, etc?

To add to the discussion, I like the potential of switching the py.iplot instances to FigureWidget output, but then this may create an issue where users don't know much about online py.iplot or py.plot. Do we want FigureWidget to be the preferred method for plotting and displaying charts?

Beyond that I think there could be another approach to teaching the differences and the capabilities of offline plotting and whether or not an account is needed for X, Y, Z. How about appending to the documentation intro blurbs (#4 of https://github.com/plotly/documentation/blob/source-design-merge/_posts/python/README.md#create-python-documentation)?

What do you all think?

[jonmmease]

@Kully

Jon, where are you noticing this misconception the most? Is it through forum posts, word of mouth, conferences, etc?

Actually all of the above 🙂

• I have colleges who wrote off plotly years ago, before the open source release and offline support, because uploading data to a public cloud is not an option. And that impression is still what first comes to their mind when I talk about plotly.py.
• Here are some recent reddit/hacker news comments:

I want to use plotly so badly but I don't want to sink an investment into another sticky commercial ecosystem -- I've had to do that with Mathematica and Matlab, I don't want to do it again. How good/bad is plotly in comparison? link

It says open source, but is it self-contained? Can it run on a machine that's off the network? I was under the impression that only JavaScript Plot.ly could run offline. Thanks! link

• I also heard similar comments from several people I talked to at SciPy last month.

cc @jackparmer

[Kully]

I have colleges who wrote off plotly years ago, before the open source release and offline support, because uploading data to a public cloud is not an option.

This reminds me of a personal friend's worry as well.

[jonmmease]

@Kully

To add to the discussion, I like the potential of switching the py.iplot instances to FigureWidget output, but then this may create an issue where users don't know much about online py.iplot or py.plot. Do we want FigureWidget to be the preferred method for plotting and displaying charts?

Setting constraints aside for a moment, here's where I would like to end up. In plotly/plotly.py#1098 I mention the idea of creating a generic plotly.io.show function that would abstract over different backends for displaying figures (we currently have 5). Like matplotlib, the active backend could be configured in code at the top of the notebook, or it could be configured with an environment variable or in the a the user's ~/.plotly settings.

Then, all of the general docs would use go.Figure to construct figures and io.show to display them. These docs would have a blurb at the top linking to a page dedicated to explaining the concept of backends with descriptions of each one. This has the advantage of allowing people to run the general examples with whatever their preferred backed is.

The widget specific docs would use go.FigureWidget to construct figures and would explicitly configure the notebook-widgets backed.

The plot.ly specific docs would explicitly configure the backend to be plot.ly-notebook (plotly.plotly.iplot) or plot.ly-browser (plotly.plotly.plot), and use io.show to display figures.

And just to be clear: I'm not suggesting removing anything. People could keep using plot/iplot and not mess with the idea of backends, but the docs would shift to encouraging the use of io.show.

Over the next few weeks I hope to get a better idea of how much work would actually be involved in adding the notion of backends into the plotly.py codebase, but at this point I don't see why it would be very complicated.

[nicolaskruchten]

Pretty sure we knocked this one out of the park :)