New Orca-based static image export tutorials for plotly.py 3.2.0

[jonmmease]

Overview

This PR contains two tutorials covering the new orca-based static image export functionality coming to plotly.py 3.2.0 (Not release yet).

See plotly/plotly.py#1120 for the corresponding PR in plotly.py.

Tutorials

Static Image Export

The legacy Static Image Export tutorial in the Plotly Fundamentals section has been overwritten by a new orca-based tutorial. This page is already the first google search result for "plotly image export", so this is the new page we want people to find first.

This tutorial covers installation instructions and the new plotly.io.to_image and plotly.io.write_image functions.

Orca Management

In addition, a new Orca Management tutorial has been added to the Plotly Fundamentals section.

This tutorial covers the lower level API for managing the orca server process.

Thumbnails

Thumbnails have been created and uploaded to S3

Notebooks

• Upload notebooks to support "Download this Notebook"

Timeline

If possible, I would like to work to get this PR reviewed and in final form by the end of this week. I'm aiming to release plotly.py 3.2.0 next Monday or Tuesday (Sept 3rd, or 4th), and I'd like to have these tutorials deployed just before the announcement.

Also, please try out the orca integration! plotly.py 3.2.0 alpha 2 is on PyPI and the anaconda plotly channel. See current instructions at https://github.com/jonmmease/plotly_orca_notebooks

cc @chriddyp @jackparmer

[bcdunbar]

Content-wise this is great 👌 Only a couple minor suggestions,

• Capitalize all headers
• Perhaps update the order so they are next to each other

@nicolaskruchten is the https://plot.ly/python/static-image-export/#supported-formats section required in the new doc?

@jonmmease I'll pin the notebook_demo account info in other channel (incase you don't have it already).

[jonmmease]

Thanks for taking a look @bcdunbar ,

Capitalizing the headers sounds fine if that's more consistent with our desired style. And updating the order is fine by me.

Your "Sypported formats" question did remind me that I want to pull in that Note/disclaimer about which traces support fully vectorized output.

BTW, did you try out installing and running the examples notebooks? I'm still looking for testing feedback 🙂

[jonmmease]

Ok, I just pushed an update that covers the comments above. But I have a couple of questions / notes.

• I uploaded the notebooks to the notebook_demo account, and set the URLs in the notebooks, but the links don't seem to do anything in Firefox. In fact, the links don't work for me in Firefox on the published documentation pages either. They do work in Chrome though. Is this a known issue or should I open an issue?
• There's a page that shows up in google search results at https://plot.ly/python/static-image-export-old/. I'd like to get rid of this page, but I don't see it in this repo. Is this hosted somewhere else?
• My pre-formatted markdown code blocks are getting strange coloring (image below). I don't see the coloring in the notebook with the CSS style applied, just in the html export. Any ideas what might be going on here?

Other note: The current version displayed in these notebooks is 3.2.0a2, so I'll need to regenerate them using a branch that displays the version as 3.2.0.

Thanks!

[bcdunbar]

links don't seem to do anything in Firefox

It doesn't look like the Firefox notebook download is a known issue - definitely worth opening an issue.

There's a page that shows up in google search results at https://plot.ly/python/static-image-export-old/.

I've come across a few of these that I haven't been able to find. For those, we add a new file here https://github.com/plotly/documentation/tree/source-design-merge/_posts/python/redirects and add a redirect. For example,

---
permalink: python/bubble-charts-tutorial/
redirect_to: https://plot.ly/python/bubble-charts/
sitemap: false
---

My pre-formatted markdown code blocks are getting strange coloring (image below)

I think this may be the custom notebook css that is applied https://github.com/plotly/documentation/blob/source-design-merge/scss/_components/_highlighting.scss

[bcdunbar]

did you try out installing and running the examples notebooks? I'm still looking for testing feedback

Yup, everything worked as expected. I'm on a windows machine so only the export of EPS doesn't work for me but the error message is super clear about why 👍

[bcdunbar]

The only error I can see some users making between these two docs, is if they start with orca-management.ipynb and try out the code without actually installing dependencies. Though, a quick check back to the Overview links them.

[jonmmease]

Firefox issue at #1060

[jonmmease]

Hmm, it looks like the highlighting culprit is highlight.js. Looks like it's auto-detecting those code block as SQL.

When I totally disable it for this page everything looks fine. The Python code is highlighted by the notebook and nbconvert.

Do you know when highlight.js is supposed to be helpful? I image it's might be needed for other languages, but I wonder if we could disable it for the Python pages since Jupyter/nbconvert takes care of this.

[jonmmease]

Ok, I made a few updates.

• I disabled the highlight.js highlighting for pages with page.language equal to 'python'. This fixes that crazy formatting on code cells that should not have highlighting.
• I added some CSS tweaks to fix what I saw as mis-alignments in the cell input/output (see below)

Before:

After:

What do you think?

[bcdunbar]

I disabled the highlight.js highlighting for pages with page.language equal to 'python'

I'm fine with it - I had a look through a few docs and removing highlight.js doesn't seem to be an issue. @cldougl might have a better idea about this though.

CSS tweaks to fix what I saw as mis-alignments

Yeah this is great too. Because you edited the scss file, you'll need to update main.css by running gulp build https://github.com/plotly/documentation/blob/source-design-merge/style_README.md

Once that is done and notebooks regenerated with 3.2.0 version, it is a 💃 from me. Thanks for making all these additional styling commits 🙇

[jackparmer]

Redirect for mystery page here:
https://github.com/plotly/documentation/blob/source-design-merge/_posts/python/redirects/2018-08-30-static-image.html
But we should also figure out if there are more of these old format pages and where they live.

[jonmmease]

Alright, notebooks re-generated (and re-uploaded) and CSS built with gulp and committed. I also tested to verify that the new redirect is working.

So for this to go live on ~Tuesday of next week, when should this be merged?

Thanks for your help @bcdunbar!

[bcdunbar]

No worries @jonmmease

You can merge it into source-design-merge when you're ready and we can deploy to gh-pages (live) on Tuesday. Alternatively, you could merge on Tuesday (or another day if later) and we can redeploy.

[jonmmease]

Great, I'll merge as soon as I'm confident there are no blockers for the release.

Also, how do we update the "Full Reference"? I'd like to bump that up to plotly.js 1.40.1 as well.

[jonmmease]

Alright, going to merge this now. Tentative deploy target of tomorrow, but that may slip until Thursday.
Thanks @bcdunbar

[cldougl]

@jonmmease Full Reference is updated on deploy from the v2 plot schema endpoint: https://api.plot.ly/v2/plot-schema
That endpoint is synced with the plotly.js version that is in streambed.
This should not have to be done manually, but rather is automated on deploy after plotly.js is updated in streambed.