Getting started section #33

jonmmease · 2019-06-25T13:42:21Z

This PR updates the "Getting started" page with updated detailed installation instructions and a "Where to next?" section with links out the the various categories of trace types, the creating and updating figures page, the renderers page, the theming page, the figure reference, and Dash.

@nicolaskruchten @emmanuelle

Doc upgrade checklist:

old boilerplate at top and bottom of file has been removed
Every example is independently runnable and is optimized for short line count
no more plot() or iplot()
graph_objs has been renamed to graph_objects
fig = <something> call is high up in each example
minimal creation of intermediate trace objects
fig.show() at the end of each example
v4upgrade: true metadata added
minimize usage of hex codes for colors in favour of those in https://github.com/plotly/plotly.py-docs/issues/14

chriddyp · 2019-06-25T14:02:20Z

notebooks/getting-started.md

-<br>
-and set your credentials:
+## Overview
+The plotly Python library ([plotly.py](https://plot.ly/python/)) is an interactive, [open-source](https://github.com/plotly/plotly.py) plotting library that supports over 30 unique chart types covering a wide range of statistical, financial, geographic, scientific, and 3-dimensional use-cases.


haha, right!

emmanuelle · 2019-06-25T14:05:23Z

notebooks/getting-started.md

-    "stream_ids": ["ylosqsyet5", "h2ct8btk1s", "oxz4fm883b"],
-    "api_key": "lr1c37zw81"
-}
+$ pip install plotly==4.0.0


This is bound to evolve, why not pip install -U plotly

The trouble is the JupyterLab section down below. The python and jupyterlab plotly extensions have to have versions that line up, and the package managers can't help with that.

We haven't talked through the whole workflow yet, but I was thinking we were going to rebuild the docs for each release, and so I though updating these versions at that point wouldn't be a big deal.

FWIW, the Dash User Guide does this as well. https://dash.plot.ly/installation

@nicolaskruchten Do you have thoughts on including version constraints here?

let's go with absolute versions for now I guess. will be a pain and we will automate someday :)

emmanuelle · 2019-06-25T14:08:36Z

notebooks/getting-started.md

-                             sharing='private')
+import plotly.graph_objects as go
+fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
+fig


fig or fig.show()?

For FigureWidget it needs to be fig (or IPython.display.display).

OK but if I copy and paste the code above in a jupyter notebook cell nothing is displayed, while if I write fig.show() the chart is displayed. I must be missing something ??

Using 4.0.0a3

classic notebook I assume? What do you get for jupyter nbextension list?

chriddyp · 2019-06-25T14:09:20Z

notebooks/getting-started.md


-By default all plots are set to **public**.  Users with free account have the permission to keep one private plot. If you need to save private plots, [upgrade to a pro account](https://plot.ly/plans). If you're a [Personal or Professional user](https://plot.ly/settings/subscription/?modal=true&utm_source=api-docs&utm_medium=support-oss) and would like the default setting for your plots to be private, you can edit your Plotly configuration:
+This package contains everything you need to write figures to standalone HTML files.


I wonder if we should include a blockquote with something like:

Note that no internet connection or account is required - this library is now "offline" by default.
In the past, this documentation emphasized publishing graphs to the https://plot.ly web service "Chart Studio". Publishing is now done with a separate chart_studio package, see below for more details.

That wording could be cleaned up. cc @nicolaskruchten too

Good idea. I added a note in 87ce12a.

emmanuelle · 2019-06-25T14:11:37Z

notebooks/getting-started.md

-```python
-import plotly
-help(plotly.offline.plot)
+$ pip install plotly-geo==1.0.0


why freeze the version number?

plotly.py doesn't depend on plotly-geo so if we add a new dataset to plotly-geo and up the version then people won't automatically get it when they update the plotly package. We will have runtime checks to catch it, but I guess my preference is to document the explicit compatible versions that the docs are built with.

See note above as well regarding the JupyterLab rationale, though that isn't as relevant to plotly-geo.

emmanuelle · 2019-06-25T14:18:03Z

notebooks/getting-started.md

-### Using Plotly with Pandas
+### Chart Studio Support
+The `chart-studio` package can be used to upload plotly figures to Plotly's Chart
+Studio Cloud or On-Prem services.  This package can be installed using pip...


link to https://plot.ly/online-chart-maker/

emmanuelle · 2019-06-25T14:22:37Z

notebooks/getting-started.md

-```python
-from IPython.display import display, HTML
+## Where to next?
+Now that you have everything installed, you are ready to start reading and running examples of [basic charts](https://plot.ly/python/basic-charts/), [statistical charts](https://plot.ly/python/statistical-charts/), [scientific charts](https://plot.ly/python/scientific-charts/), [financial charts](https://plot.ly/python/#financial-charts), [geographic charts](https://plot.ly/python/maps/), and [3-dimensional charts](https://plot.ly/python/3d-charts/).



I would also add a link to notebooks explaining how to configure figures, such as some of https://plot.ly/python/plotly-fundamentals/ (although this index page is quite misc).

Good idea. I added two more links in 8df26a3.

it's a lot less misc now! The reorg PR went through so it's all actual fundamentals now... phew :)

emmanuelle

Thanks !

nicolaskruchten · 2019-06-27T02:02:32Z

notebooks/getting-started.md


-By default all plots are set to **public**.  Users with free account have the permission to keep one private plot. If you need to save private plots, [upgrade to a pro account](https://plot.ly/plans). If you're a [Personal or Professional user](https://plot.ly/settings/subscription/?modal=true&utm_source=api-docs&utm_medium=support-oss) and would like the default setting for your plots to be private, you can edit your Plotly configuration:
+> Note: No internet connection or account is required to use plotly.py. Prior to version 4, this library could operate in either an "online" or "offline" mode. The documentation tended to emphasize the online mode, where graphs get published to the Chart Studio web service.  In version 4, all "online" functionality was removed from the `plotly` package and is now available as the separate, optional, `chart-studio` package (See below).  plotly.py version 4 is "offline" only, and does not include any functionality for uploading figures to cloud services.  


I would add "or payment"

and maybe bold the "no xxx required" and "not include any functionality for uploading figures to cloud services"

extend "uploading figures to" to "uploading figures or data to" ?

nicolaskruchten · 2019-06-27T02:05:20Z

notebooks/getting-started.md

+plotly.py supports static image export using the `to_image` and `write_image`
+functions in the `plotly.io` package. This functionality requires the
+installation of the plotly [orca](https://github.com/plotly/orca) command line utility and the
+[`psutil`](https://github.com/giampaolo/psutil) and [`requests`](https://2.python-requests.org/en/master/) Python packages.


should we add a note in blockquote saying something to the effect of "requests here is only used to make local requests within your machine and not to any outside services" ?

nicolaskruchten · 2019-06-27T02:07:36Z

notebooks/getting-started.md


-```python
-from IPython.display import display, HTML
+For information on configuring figure layout options (e.g. axes, titles, legends, etc) see [*Layout Options*](https://plot.ly/python/#layout-options).


this should link to fundamentals now, and ditto the styling link below IMO

jonmmease · 2019-06-27T09:52:49Z

Thanks for giving this a look @nicolaskruchten, I've incorporated your suggestions

nicolaskruchten · 2019-06-28T02:08:53Z

💃

jonmmease added 2 commits June 25, 2019 09:38

Update getting started section

9439b3e

v4upgrade: true

5d6293f

chriddyp reviewed Jun 25, 2019

View reviewed changes

emmanuelle reviewed Jun 25, 2019

View reviewed changes

chriddyp reviewed Jun 25, 2019

View reviewed changes

emmanuelle reviewed Jun 25, 2019

View reviewed changes

40!

3f82ac3

emmanuelle reviewed Jun 25, 2019

View reviewed changes

jonmmease added 4 commits June 25, 2019 10:30

Update user-guide links

9f1ed8b

Add links to style and layout options

8df26a3

Update user guide name in link

dd5402e

Added note about version 4 being "offline" only

87ce12a

nicolaskruchten reviewed Jun 27, 2019

View reviewed changes

A few review updates

d61752f

jonmmease merged commit 84cf850 into master Jun 28, 2019


		By default all plots are set to public. Users with free account have the permission to keep one private plot. If you need to save private plots, [upgrade to a pro account](https://plot.ly/plans). If you're a [Personal or Professional user](https://plot.ly/settings/subscription/?modal=true&utm_source=api-docs&utm_medium=support-oss) and would like the default setting for your plots to be private, you can edit your Plotly configuration:
		This package contains everything you need to write figures to standalone HTML files.


		By default all plots are set to public. Users with free account have the permission to keep one private plot. If you need to save private plots, [upgrade to a pro account](https://plot.ly/plans). If you're a [Personal or Professional user](https://plot.ly/settings/subscription/?modal=true&utm_source=api-docs&utm_medium=support-oss) and would like the default setting for your plots to be private, you can edit your Plotly configuration:
		> Note: No internet connection or account is required to use plotly.py. Prior to version 4, this library could operate in either an "online" or "offline" mode. The documentation tended to emphasize the online mode, where graphs get published to the Chart Studio web service. In version 4, all "online" functionality was removed from the `plotly` package and is now available as the separate, optional, `chart-studio` package (See below). plotly.py version 4 is "offline" only, and does not include any functionality for uploading figures to cloud services.

Getting started section #33

Getting started section #33

Uh oh!

Conversation

jonmmease commented Jun 25, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emmanuelle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonmmease commented Jun 27, 2019

Uh oh!

nicolaskruchten commented Jun 28, 2019

Uh oh!

Uh oh!