Black Lives Matter. Please consider donating to Black Girls Code today.
Learn about the upcoming Dash Enterprise 4.0 release in the August 5th webinar with Chris Parmer, the Inventor of Dash.

Versioned documentation (have new plotly express docs overwritten old api docs?)

I’m looking for all the old documentation for plotly before plotly express was introduced. Upgrading to a later plotly version won’t be possible for us in the near future, so I still need access to the old docs. For example, old versions of the following docs would be nice, as the APIs have changed a lot: https://plot.ly/python/axes/ .

@amittleider, you can find the older versions of our docs at https://plot.ly/python/v3. It says “v3” but those docs are also compatible with v2.

1 Like

Thank you, @michaelbabyn !

Hi @michaelbabyn Thanks for this link because I was going crazy trying to find the version 3 docs (since like the original person, I can’t upgrade any time soon but I still need to maintain the old stuff).

Is there a way this could be linked in a more obvious way? I might just be blind, but I couldn’t find any link on the Python docs telling me that this even existed anymore.

Hi @felixvelariusbos, unfortunately we’re actually going in the other direction with our v3 (v2 compatible) docs and we plan on getting rid of them in the future.

So if you plan on continuing to use and update v2/v3 of plotly.py, I would recommend looking over https://plotly.com/python/creating-and-updating-figures/ which may help you to convert the V4 style of creating charts that we recommend and use in the new docs to the older V3-compatible style.

Essentially that boils down to not being able to use the graph_objects update_* methods and the new magic underscore syndax so you’ll have to convert something like this:

import plotly.graph_objects as go
fig = go.Figure(data=go.Bar(x=[1, 2, 3], y=[1, 3, 2]))
fig.update_layout(title_text="A Bar Chart",
                  title_font_size=30)
fig.show()

to

import plotly.offline as py
data = [go.Bar(x=[1, 2, 3], y=[1, 3, 2]))]
layout = dict(
        title="A Bar Chart",
        titlefont=dict(size=30)
    )
)
fig = dict(data=data, layout=layout)
py.iplot(fig)

I.e you’ll need to replace underscores with nested dicts and you’ll have to explicitly create a layout object. Additionally, you will need to know that we changed the layout attribute titlefont to font as a subattribute of a new title object attribute (see this PR for more details about that change). This process will work for 90% of the non-plotly-express examples in the new docs

Running into similar issue where I need access to documentation for the previous version. The above link no longer seems to work. @michaelbabyn are they still available anywhere? Tnx

Hi @michaelbabyn and @rsciban

Sorry, I hadn’t seen your reply. I too can no longer find the old documentation.

I would like put in another vote for putting the old docs back. If the new documentation reflected what you just showed I would not mind…however all the new documentation heavily emphasizes Plotly Express (example: https://plotly.com/python/line-charts/), which is completely different than the old style. While it seems most pages have information on the old way of doing it…they hide the old style way at the bottom, which makes me worry that it’s going to go away.

To add to it, dumping the old documentation is going to make it harder to migrate. I’m not even using that “update_layout” method much, but based on the current docs, I’ll have convert almost every single chart I have to match the new plotly express model, and I have absolutely no idea where to start. Not having those original docs on hand to remember why I implemented things the way I did in the first place makes it even harder.

Is there a particular reason why Plotly is pushing so hard on erasing this?

Hi folks,

I’m sorry this is causing problems… Here’s how we’ve been thinking about this:

  1. Almost everything that you could do in v3 still works in v4 (see our migration guide for exceptions: https://plotly.com/python/v4-migration/) providing you don’t use any new Plotly.js features or attributes.
  2. Our old v3 docs heavily emphasized our Chart Studio product: every single page said you had to sign up to our service to get started and every single example suggested you had to host your chart on Chart Studio, and this turned off thousands of potential users. In version 4 we cut this out and put it into a separate package.
  3. Some of the v3 docs hadn’t been touched or regenerated since the early v2 days and hence were really misleading/out of date even before v4 came out.
  4. When we released v4, it took hundreds of person-hours to rewrite the docs to our current standards, and we simply don’t have the resources to upgrade our old v3 docs to fix the problems they had.
  5. Our v3 docs were ranking higher than our v4 docs in Google searches in some cases, leading to confused users, and people still using/documenting/blogging about old patterns to accomplish certain tasks for which there are much better approaches now.

Taking all these points together, we felt it would be the least-bad option to continue investing all of our time and energy into making the v4 docs the best we could make them, and to stop hosting the v3 docs so as to make sure we’re not confusing new users about how Plotly.py works, and especially to stop reinforcing the old notion that Plotly.py is mostly a client for Chart Studio Cloud.

All that said, I believe we still have the old docs in our https://github.com/plotly/documentation repo in the gh-pages branch if you go back about a year… Maybe I could provide some instructions about how to download and locally browse them if people are really interested?

PS: regarding the “old style going away”… as I’ve said, almost everything in v3 is still possible with v4, and we have no plans to get rid of graph_objects or otherwise breaking that API :slight_smile:

1 Like

Hi @felixvelariusbos ,

The new style it’s not a plotly express style, but it’s the new style for plotly.py (graph_objects)(see here https://plotly.com/python/plotly-express/ what is plotly express).

To understand how to interpret the new style, please read this answer to a question:

Follow-up: I went back through our Github history and tagged a particular commit, pre-v4-switchover in May 2019, around Plotly.py 3.9. As a result, you can now do the following:

  • download the tarball and unpack it (NB it’s around 200 megs compressed, 900 megs uncompressed!)
  • in that directory, run python -m http.server which will spawn a local webserver
  • point your browser to http://localhost:8000/api/index.html
  • browse our docs roughly they way they looked on May 14, 2019! You’ll see some CSS breakage as some common assets and URLs have changed since then, but there’s not a lot I can do about that.
1 Like

@nicolaskruchten @empet I appreciate you all taking the time to write this up, and do a tag in the Git repo for the old-style. I’ll definitely check it out.

I personally appreciate the switch away from emphasizing Chart Studio, so no complaints there! And appreciate the clarification there are no plans to get rid of graph_objects. I’m just paranoid.

1 Like