Merge branch 'doc-prod' into jupyterlab-clarification

Author: marthacryan

Diff for: .circleci/config.yml

@@ -374,7 +374,7 @@ jobs:
 
   full_build:
     docker:
-      - image: continuumio/miniconda3
+      - image: continuumio/miniconda3:24.3.0-0
         environment:
           LANG: en_US.UTF-8
     resource_class: large
@@ -599,3 +599,4 @@ workflows:
       - python_38_orca
       - python_39_percy
       - build-doc
+

Diff for: CHANGELOG.md

@@ -2,6 +2,24 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [5.23.0] - 2024-07-23
+
+### Updated
+- Updated Plotly.js from version 2.32.0 to version 2.34.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2340----2024-07-18) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
+  - Add `subtitle` attribute to `layout.title` to enable adding subtitles to plots [[#7012](https://github.com/plotly/plotly.js/pull/7012)]
+  - Introduce "u" and "s" pseudo html tags to add partial underline and strike-through styles to SVG text elements [[#7043](https://github.com/plotly/plotly.js/pull/7043)]
+  - Add geometric mean functionality and 'geometric mean ascending' + 'geometric mean descending' to `category_order` on cartesian axes [[#6223](https://github.com/plotly/plotly.js/pull/6223)],
+   with thanks to @acxz and @prabhathc for the contribution!
+  - Add axis property `ticklabelindex` for drawing the label for each minor tick n positions away from a major tick,
+   with thanks to @my-tien for the contribution! [[#7036](https://github.com/plotly/plotly.js/pull/7036)]
+  - Add property `ticklabelstandoff` and `ticklabelshift` to cartesian axes to adjust positioning of tick labels,
+   with thanks to @my-tien for the contribution! [[#7006](https://github.com/plotly/plotly.js/pull/7006)]
+  - Add `x0shift`, `x1shift`, `y0shift`, `y1shift` to shapes to add control over positioning of shape vertices on (multi-)category axes,
+   with thanks to @my-tien for the contribution! [[#7005](https://github.com/plotly/plotly.js/pull/7005)]
+- Specify Python version 3.8-3.11 for development virtual environments and pin `pytest` at version 8.1.1 to match.
+- Update `IntegerValidator` to handle `extras` option to allow supporting additional keyword values. For example, 'bold' and 'normal' as well as integers as used in font weights [#4612].
+
+
 ## [5.22.0] - 2024-05-01
 
 ### Updated

Diff for: README.md

@@ -31,9 +31,16 @@
     </tr>
 </table>
 
+<div align="center">
+  <a href="https://dash.plotly.com/project-maintenance">
+    <img src="https://dash.plotly.com/assets/images/maintained-by-plotly.png" width="400px" alt="Maintained by Plotly">
+  </a>
+</div>
+
+
 ## Quickstart
 
-`pip install plotly==5.22.0`
+`pip install plotly==5.23.0`
 
 Inside [Jupyter](https://jupyter.org/install) (installable with `pip install "jupyterlab>=3" "ipywidgets>=7.6"`):
 
@@ -78,13 +85,13 @@ Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is
 plotly.py may be installed using pip...
 
 ```
-pip install plotly==5.22.0
+pip install plotly==5.23.0
 ```
 
 or conda.
 
 ```
-conda install -c plotly plotly=5.22.0
+conda install -c plotly plotly=5.23.0
 ```
 
 ### JupyterLab Support
@@ -106,7 +113,7 @@ The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**,
 
 ```
 # JupyterLab 2.x renderer support
-jupyter labextension install jupyterlab-plotly@5.22.0 @jupyter-widgets/jupyterlab-manager
+jupyter labextension install jupyterlab-plotly@5.23.0 @jupyter-widgets/jupyterlab-manager
 ```
 
 Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.

Diff for: binder/requirements.txt

@@ -1,11 +1,11 @@
 jupytext
-plotly==5.22.0
+plotly==5.23.0
 jupyter
 notebook
-pandas==1.2.0
-statsmodels==0.12.1
+pandas==2.2.2
+statsmodels==0.14.2
 scipy
-patsy==0.5.1
+patsy==0.5.6
 numpy
 plotly-geo
 psutil

Diff for: contributing.md

@@ -125,13 +125,16 @@ learn and become confident about git, like http://try.github.io/.
 
 ### Create a virtual environment for plotly development
 
-You can use either [conda][conda-env] or [virtualenv][virtualenv] to create a virtual environment for plotly development, e.g.
+You can use either [conda][conda-env] or [virtualenv][virtualenv] to create a virtual environment for plotly development, e.g.:
 
 ```bash
-conda create -n plotly-dev python
+conda create -n plotly-dev python=3.11
 conda activate plotly-dev
 ```
 
+As of May 2024 our dependencies have been tested against Python versions 3.8 to 3.11.
+We will support Python 3.12 and higher versions soon.
+
 [conda-env]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands
 [virtualenv]: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 

Diff for: doc/apidoc/Makefile

@@ -36,7 +36,7 @@ help:
 	# Remove files which were added only for docstring generation
 	rm ../../packages/python/plotly/plotly/colors/diverging.py ../../packages/python/plotly/plotly/colors/sequential.py ../../packages/python/plotly/plotly/colors/qualitative.py ../../packages/python/plotly/plotly/colors/cyclical.py ../../packages/python/plotly/plotly/colors/colorbrewer.py ../../packages/python/plotly/plotly/colors/carto.py ../../packages/python/plotly/plotly/colors/cmocean.py
 	rm ../../packages/python/plotly/plotly/express/colors/diverging.py ../../packages/python/plotly/plotly/express/colors/sequential.py ../../packages/python/plotly/plotly/express/colors/qualitative.py ../../packages/python/plotly/plotly/express/colors/cyclical.py ../../packages/python/plotly/plotly/express/colors/colorbrewer.py ../../packages/python/plotly/plotly/express/colors/carto.py ../../packages/python/plotly/plotly/express/colors/cmocean.py
-	rename 's/graph_objs/graph_objects/' _build/html/*.html _build/html/generated/*.html
+	rename 's/graph_objs/graph_objects/' _build/html/*.html _build/html/generated/*.html _build/html/generated/generated/*.html
 	mv _build/html/generated/plotly.graph_objs.html _build/html/generated/plotly.graph_objects.html
 	sed -i 's/graph_objs/graph_objects/g' _build/html/*.html
 	sed -i 's/graph_objs/graph_objects/g' _build/html/*.inv

Diff for: doc/apidoc/conf.py

@@ -26,7 +26,7 @@
 # The short X.Y version
 version = ""
 # The full version, including alpha/beta/rc tags
-release = "5.22.0"
+release = "5.23.0"
 
 
 # -- General configuration ---------------------------------------------------

Diff for: doc/python/3d-volume.md

@@ -86,7 +86,7 @@ np.random.seed(0)
 l = 30
 X, Y, Z = np.mgrid[:l, :l, :l]
 vol = np.zeros((l, l, l))
-pts = (l * np.random.rand(3, 15)).astype(np.int)
+pts = (l * np.random.rand(3, 15)).astype(int)
 vol[tuple(indices for indices in pts)] = 1
 from scipy import ndimage
 vol = ndimage.gaussian_filter(vol, 4)

Diff for: doc/python/axes.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.1
+      jupytext_version: 1.16.3
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.11
+    version: 3.10.14
   plotly:
     description: How to adjust axes properties in Python - axes titles, styling and
       coloring axes and grid lines, ticks, tick labels and more.
@@ -367,7 +367,7 @@ fig.show()
 
 *New in 5.19*
 
-If `tickangle` is not explicitly set, its default value is `auto`, meaning if the label needs to be rotated to avoid labels overlapping, it will rotate by either 30 or 90 degrees. Using `autotickangles`, you can also specify a list of angles for `tickangle` to use. If `tickangle` is `auto` and you provide a list of angles to `autotickangles`, the label angle will be set to the first value in the list that prevents overlap. 
+If `tickangle` is not explicitly set, its default value is `auto`, meaning if the label needs to be rotated to avoid labels overlapping, it will rotate by either 30 or 90 degrees. Using `autotickangles`, you can also specify a list of angles for `tickangle` to use. If `tickangle` is `auto` and you provide a list of angles to `autotickangles`, the label angle will be set to the first value in the list that prevents overlap.
 
 ```python
 import plotly.express as px
@@ -390,14 +390,18 @@ Here is an example.
 import plotly.graph_objects as go
 import pandas as pd
 
-# Load and filter Apple stock data for 2016
 apple_df = pd.read_csv(
-    "https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv",
-    parse_dates=["Date"],
-    index_col="Date"
+    "https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv"
 )
 
-apple_df_2016 = apple_df["2016"]
+# Convert 'Date' column to datetime format
+apple_df['Date'] = pd.to_datetime(apple_df['Date'])
+
+# Set 'Date' column as index
+apple_df.set_index('Date', inplace=True)
+
+# Filter for 2016
+apple_df_2016 = apple_df.loc['2016']
 
 # Create figure and add line
 fig = go.Figure()
@@ -444,6 +448,62 @@ fig.update_yaxes(minor_ticks="inside")
 fig.show()
 ```
 
+#### Adjust Tick Label Positions
+
+*New in 5.23*
+
+You can adjust tick label positions by moving them a number of pixels away from the axis using `ticklabelstandoff` or along the axis using `ticklabelshift`.
+
+In this example, `ticklabelshift=25` shifts the labels 25 pixels to the right along the x-axis. By providing a negative value, we could move the labels 25 pixels to the left, (`ticklabelshift=-25`).
+
+Here, `ticklabelstandoff=15` moves the labels 15 pixels further away from the x-axis. A negative value here would move them closer to the axis.
+
+```python
+import plotly.express as px
+
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
+
+fig = px.line(df, x='Date', y='AAPL.High')
+
+fig.update_layout(
+    xaxis=dict(
+        ticks='outside',
+        ticklen=10,
+        ticklabelshift=25,
+        ticklabelstandoff=15
+    )
+)
+
+fig.show()
+```
+
+#### Use Minor Tick for Label
+
+*New in 5.23*
+
+On date or linear axes, use `ticklabelindex` to draw a label for a minor tick instead of a major tick.
+
+To draw the label for the minor tick before each major tick, set `ticklabelindex=-1`, like in the following example.
+
+```python
+import plotly.express as px
+
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
+
+fig = px.line(df, x='Date', y='AAPL.High')
+
+fig.update_layout(
+    xaxis=dict(
+        minor=dict(ticks='outside'),
+        ticks='outside',
+        ticklen=10,
+        ticklabelindex=-1
+    )
+)
+
+fig.show()
+```
+
 ### Axis lines: grid and zerolines
 
 ##### Toggling Axis grid lines
@@ -599,7 +659,7 @@ fig.show()
 
 *New in 5.17*
 
-You can also set just a lower or upper bound manually and have autorange applied to the other bound by setting it to `None`. In the following example, we set a an upper bound of 4.5 on the x axes, while specifying `None` for the lower bound, meaning it will use autorange. On the y axes, we set the lower bound, and use `None` for the upper bound, meaning that uses autorange. 
+You can also set just a lower or upper bound manually and have autorange applied to the other bound by setting it to `None`. In the following example, we set a an upper bound of 4.5 on the x axes, while specifying `None` for the lower bound, meaning it will use autorange. On the y axes, we set the lower bound, and use `None` for the upper bound, meaning that uses autorange.
 
 ```python
 import plotly.express as px
@@ -857,7 +917,7 @@ fig.show()
 
 #### <code>nonnegative</code>, <code>tozero</code>, and <code>normal</code> Rangemode
 
-When you don't specify a range, autorange is used. It's also used for bounds set to `None` when providing a `range`. 
+When you don't specify a range, autorange is used. It's also used for bounds set to `None` when providing a `range`.
 
 The axis auto-range calculation logic can be configured using the `rangemode` axis parameter.
 
@@ -898,7 +958,7 @@ fig.update_xaxes(autorangeoptions=dict(maxallowed=5))
 fig.show()
 ```
 
-##### Clip Minimum and Maximum 
+##### Clip Minimum and Maximum
 
 You can also clip an axis range at a specific maximum or minimum value with `autorangeoptions.clipmax` and `autorangeoptions.clipmin`.
 
@@ -916,7 +976,7 @@ fig.show()
 
 ##### Specify Values to be Included
 
-Use `autorangeoptions.include` to specify a value that should always be included within the calculated autorange. In this example, we specify that for the autorange calculated on the x-axis, 5 should be included. 
+Use `autorangeoptions.include` to specify a value that should always be included within the calculated autorange. In this example, we specify that for the autorange calculated on the x-axis, 5 should be included.
 
 ```python
 import plotly.express as px

Diff for: doc/python/box-plots.md

@@ -458,12 +458,12 @@ x_data = ['Carmelo Anthony', 'Dwyane Wade',
 
 N = 50
 
-y0 = (10 * np.random.randn(N) + 30).astype(np.int)
-y1 = (13 * np.random.randn(N) + 38).astype(np.int)
-y2 = (11 * np.random.randn(N) + 33).astype(np.int)
-y3 = (9 * np.random.randn(N) + 36).astype(np.int)
-y4 = (15 * np.random.randn(N) + 31).astype(np.int)
-y5 = (12 * np.random.randn(N) + 40).astype(np.int)
+y0 = (10 * np.random.randn(N) + 30).astype(int)
+y1 = (13 * np.random.randn(N) + 38).astype(int)
+y2 = (11 * np.random.randn(N) + 33).astype(int)
+y3 = (9 * np.random.randn(N) + 36).astype(int)
+y4 = (15 * np.random.randn(N) + 31).astype(int)
+y5 = (12 * np.random.randn(N) + 40).astype(int)
 
 y_data = [y0, y1, y2, y3, y4, y5]
 

Diff for: doc/python/configuration-options.md

@@ -252,7 +252,7 @@ fig.show()
 
 *New in v4.7*
 
-Some modebar buttons of Cartesian plots are optional and have to be added explicitly, using the `modeBarButtonsToAdd` config attribute. These buttons are used for drawing or erasing shapes. See [the tutorial on shapes and shape drawing](python/shapes#drawing-shapes-on-cartesian-plots) for more details.
+Some modebar buttons of Cartesian plots are optional and have to be added explicitly, using the `modeBarButtonsToAdd` config attribute. These buttons are used for drawing or erasing shapes. See [the tutorial on shapes and shape drawing](/python/shapes#drawing-shapes-with-a-mouse-on-cartesian-plots) for more details.
 
 ```python
 import plotly.express as px

Diff for: doc/python/figure-labels.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.1
+      jupytext_version: 1.16.3
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.11
+    version: 3.10.14
   plotly:
     description: How to set the global font, title, legend-entries, and axis-titles
       in python.
@@ -236,5 +236,44 @@ fig.update_layout(
 fig.show()
 ```
 
+### Adding a Plot Subtitle
+
+*New in 5.23*
+
+Add a subtitle to a plot with `layout.title.subtitle`. In the following example, we set the subtitle's `text`, and configure the `font` `color` and `size`. By default, if you don't set a font size for the subtitle, it will be `0.7` of the `title` font size.
+
+```python
+import plotly.graph_objects as go
+from plotly import data
+
+df = data.gapminder().query("continent == 'Europe' and (year == 1952 or year == 2002)")
+
+df_pivot = df.pivot(index="country", columns="year", values="lifeExp")
+
+fig = go.Figure(
+    [
+        go.Bar(
+            x=df_pivot.index, y=df_pivot[1952], name="1952", marker_color="IndianRed"
+        ),
+        go.Bar(
+            x=df_pivot.index, y=df_pivot[2002], name="2002", marker_color="LightSalmon"
+        ),
+    ],
+    layout=dict(
+        title=dict(
+            text="Life Expectancy",
+            subtitle=dict(
+                text="Life expectancy by European country in 1952 and in 2002",
+                font=dict(color="gray", size=13),
+            ),
+        )
+    ),
+)
+
+
+fig.show()
+
+```
+
 #### Reference
 See https://plotly.com/python/reference/layout/ for more information!