Updates to examples in fundamentals section #2201

jdamiba · 2020-02-14T23:16:59Z

The purpose of this PR is to update 3 of our examples.

doc/python/renderers.md

nicolaskruchten · 2020-02-17T17:46:23Z

doc/python/renderers.md

+
+Instead, pass your figure as the `figure` parameter to the `dcc.Graph` component. 
+
+```python


does this actually work here? I would think you'd need to escape this block somehow so it doesn't actually execute :)

nicolaskruchten · 2020-02-17T17:47:03Z

doc/python/subplots.md


-Here is an example of creating a figure with two scatter traces in side-by-side subplots.
+This function accepts two integer parameters (`rows` and `cols`), which specifiy how the subplots should be laid out.


this is probably misleading, as this function accepts many other parameters as well...

nicolaskruchten · 2020-02-17T17:47:56Z

doc/python/subplots.md

@@ -203,9 +205,9 @@ fig.show()
 ```

 #### Customizing Subplot Axes
-After a figure with subplots is created using the `make_subplots` function, its axis properties (title, font, range, grid style, etc.) can be customized using the `update_xaxes` and `update_yaxes` graph object figure methods.  By default, these methods apply to all of the x axes or y axes in the figure. The `row` and `col` arguments can be used to control which axes are targeted by the update.
+After a figure with subplots is created using the `make_subplots()` function, its axis properties (title, font, range, grid style, etc.) can be customized using the `update_xaxes` and `update_yaxes` graph object figure methods.  By default, these methods apply to all of the `x` axes or `y` axes in the figure. The `row` and `col` arguments can be used to control which axes are targeted by the update.


why put x and y in backticks here?

doc/python/subplots.md

nicolaskruchten · 2020-02-17T17:52:20Z

doc/python/subplots.md

@@ -354,7 +355,7 @@ fig.show()
 ```

 #### Subplots Types
-By default, the `make_subplots` function assumes that the traces that will be added to all subplots are 2-dimensional cartesian traces (e.g. `scatter`, `bar`, `histogram`, `violin`, etc.).  Traces with other subplot types (e.g. `scatterpolar`, `scattergeo`, `parcoords`, etc.) are supporteed by specifying the `type` subplot option in the `specs` argument to `make_subplots`.
+By default, the `make_subplots()` function assumes that the traces that will be added to all subplots are 2-dimensional cartesian traces (e.g. `scatter`, `bar`, `histogram`, `violin`, etc.).  Traces with other subplot types (e.g. `scatterpolar`, `scattergeo`, `parcoords`, etc.) are supporteed by specifying the `type` subplot option in the `specs` argument to `make_subplots`.


in general, I don't really agree with putting the () after the function name everywhere (this comment applies to this whole PR btw). The function is properly named make_subplots and calling it with no parameters like make_subplots() will probably result in an error. It's probably OK to use this for something like "the .show() method" as that actually will work with no arguments.

Also note: maybe we haven't used it super consistently, but the leading . in "the .show() method" is actually informative IMO in that it reminds the reader that show isn't a free function but a method of a figure. As a matter of style we could say "the fig.show method" or "the .show method of every go.Figure object" or something.

In any case, unless you're going to fully standardize the usage of this kind of thing throughout the docs, I find it pretty distracting and hard to review changes like this :)

nicolaskruchten · 2020-02-17T17:53:10Z

doc/python/renderers.md

@@ -171,18 +175,17 @@ fig.show(renderer="png")
 ```

 ###### `pdf`
-This renderer displays figures as static PDF files. This is especially useful for notebooks that will be exported to PDF files using the LaTeX export capabilities of nbconvert.
+This renderer displays figures as static `.pdf` files. This is especially useful for notebooks that will be exported to `.pdf` files using the `LaTeX` export capabilities of `nbconvert`.


here the usage of backticks is questionable also... "static PDF files" is acceptable, no? It's not clear why "static .pdf files" is clearer or better :)

nicolaskruchten · 2020-02-17T17:53:43Z

doc/python/renderers.md


-> Note: Adding the Plotly.js bundle to the notebook does add a few megabytes to the notebook size, so if you can count on having an internet connection you may want to consider the `notebook_connected` renderer.
+> Note: Adding the `plotly.js` bundle to the notebook adds a few megabytes to the notebook size. If you can count on always having an Internet connection, you may want to consider using the `notebook_connected` renderer if notebook size is a constraint.


I don't think we should backtick "plotly.js" ...

nicolaskruchten · 2020-02-17T17:54:19Z

doc/python/renderers.md

- 3. Using a `FigureWidget` in an ipywidgets context
+In general, there are three different approaches you can take in order to display figures:
+
+ 1. Using the `renderers` framework in the context of a script or notebook


Here also I think the usage of backticks for renderers is going a bit too far IMO...

nicolaskruchten · 2020-02-17T17:55:00Z

doc/python/creating-and-updating-figures.md


-`go` figures also support `update_layout_images` in order to [update background layout images](/python/images/), `update_annotations` in order to [update annotations](/python/text-and-annotations/#multiple-annotations), and `update-shapes` in order to [update shapes](/python/shapes/).
+Figures created with the `plotly.graph_objects` module also support:


This isn't totally correct: all figures support this, including those created with make_subplots and PX...

nicolaskruchten · 2020-02-17T17:57:08Z

As a general comment, I think the style rule around backticks could be something like "text that might reasonably end up being executed gets backticks"... this excludes LaTeX and "x axis" but includes nbconvert and .show and go.Figure and px.scatter ... thoughts?

jdamiba · 2020-02-17T18:46:57Z

@nicolaskruchten I agree with your style comments and think this is a good opportunity to standardize.

To summarize, if a piece of text is likely to be copied into a development environment, it should be styled with backticks. So variable names like fig and descriptions of method calls like fig.show(), .show(), and make_subplots should be in backticks.

File formats such as PDF and JPEG should not be in backticks.

What about package and library names like plotly.py, plotly.js or htmlwidgets? I think they should get backticks.

jdamiba · 2020-02-19T19:25:23Z

@nicolaskruchten Can you please take another look at this.

nicolaskruchten · 2020-04-06T19:52:11Z

doc/requirements.txt

@@ -23,5 +23,4 @@ recommonmark
 pathlib
 python-frontmatter
 datashader
-pyarrow
-cufflinks==0.17.3
+pyarrow


this diff should not be in this PR: we need cufflinks installed

I'll make the change and merge this

jdamiba changed the title ~~fixups to grammar and wording~~ Updates to examples in fundamentals section Feb 14, 2020

emmanuelle reviewed Feb 17, 2020

View reviewed changes

doc/python/renderers.md Show resolved Hide resolved

nicolaskruchten reviewed Feb 17, 2020

View reviewed changes

doc/python/subplots.md Show resolved Hide resolved

nicolaskruchten reviewed Feb 17, 2020

View reviewed changes

emmanuelle added the documentation label Feb 19, 2020

jdamiba force-pushed the wording-fixups branch from 86705d9 to c03bea8 Compare April 6, 2020 17:51

nicolaskruchten reviewed Apr 6, 2020

View reviewed changes

Joseph Damiba and others added 6 commits April 6, 2020 15:55

fixups to grammar and wording

5e53dde

fixups

55a2777

add dependencies

9c6b561

fixups

b080ae6

use html escape

cfc8126

fixup

9801eea

nicolaskruchten force-pushed the wording-fixups branch from c03bea8 to 9801eea Compare April 6, 2020 19:55

nicolaskruchten merged commit 3f78485 into doc-prod Apr 6, 2020

nicolaskruchten deleted the wording-fixups branch June 19, 2020 16:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Updates to examples in fundamentals section #2201

Updates to examples in fundamentals section #2201

Uh oh!

jdamiba commented Feb 14, 2020

Uh oh!

Uh oh!

nicolaskruchten Feb 17, 2020

Uh oh!

nicolaskruchten Feb 17, 2020

Uh oh!

nicolaskruchten Feb 17, 2020

Uh oh!

Uh oh!

nicolaskruchten Feb 17, 2020

Uh oh!

nicolaskruchten Feb 17, 2020

Uh oh!

nicolaskruchten Feb 17, 2020

Uh oh!

nicolaskruchten Feb 17, 2020

Uh oh!

nicolaskruchten Feb 17, 2020

Uh oh!

nicolaskruchten commented Feb 17, 2020

Uh oh!

jdamiba commented Feb 17, 2020 •

edited

Loading

Uh oh!

jdamiba commented Feb 19, 2020

Uh oh!

nicolaskruchten Apr 6, 2020

Uh oh!

nicolaskruchten Apr 6, 2020

Uh oh!

Uh oh!


		Instead, pass your figure as the `figure` parameter to the `dcc.Graph` component.

		```python


		Here is an example of creating a figure with two scatter traces in side-by-side subplots.
		This function accepts two integer parameters (`rows` and `cols`), which specifiy how the subplots should be laid out.


		> Note: Adding the Plotly.js bundle to the notebook does add a few megabytes to the notebook size, so if you can count on having an internet connection you may want to consider the `notebook_connected` renderer.
		> Note: Adding the `plotly.js` bundle to the notebook adds a few megabytes to the notebook size. If you can count on always having an Internet connection, you may want to consider using the `notebook_connected` renderer if notebook size is a constraint.


		`go` figures also support `update_layout_images` in order to [update background layout images](/python/images/), `update_annotations` in order to [update annotations](/python/text-and-annotations/#multiple-annotations), and `update-shapes` in order to [update shapes](/python/shapes/).
		Figures created with the `plotly.graph_objects` module also support:

Uh oh!

Updates to examples in fundamentals section #2201

Updates to examples in fundamentals section #2201

Uh oh!

Conversation

jdamiba commented Feb 14, 2020

Uh oh!

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!

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!

nicolaskruchten commented Feb 17, 2020

Uh oh!

jdamiba commented Feb 17, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdamiba commented Feb 19, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jdamiba commented Feb 17, 2020 •

edited

Loading