DOC: Add note about linear colorbar scale option for TwoSlopeNorm (matplotlib#30639)

* DOC: Add note about linear colorbar scale option for TwoSlopeNorm

Addresses matplotlib#22197 by documenting the cb.ax.set_yscale('linear')
workaround for users who prefer linear colorbar spacing instead of
the default scaled spacing introduced in matplotlib 3.5.

* FIX: Apply pre-commit fixes (end-of-file and line endings)

* FIX: Use proper reStructuredText markup for inline code and class references

* DOC: Add visual example comparing scaled vs linear colorbar for TwoSlopeNorm

Replace note with side-by-side example showing:
- Left: Default scaled colorbar (centered at midpoint)
- Right: Linear colorbar using cb.ax.set_yscale('linear')

Addresses maintainer feedback from @jklymak to make the difference
more clear with a visual demonstration.

* DOC: Refine TwoSlopeNorm colorbar documentation per maintainer feedback

- Change title from 'norms with a scale' to TwoSlopeNorm-specific
- Clarify that colorbar is divided into two equal parts
- Explain screen-space vs data range difference
- Note that color-to-value mapping remains unchanged
- Address review comments from @timhoffm

* FIX: Add proper reStructuredText markup for code references

- Add backticks around .TwoSlopeNorm class reference
- Use double backticks for cb.ax.set_yscale('linear') code snippet
- Fixes documentation build errors

* Update galleries/users_explain/colors/colormapnorms.py

Co-authored-by: Tim Hoffmann <[email protected]>

* DOC: Address jklymak review feedback on colorbar explanation

- Rewrite explanation to avoid 'screen space' term per jklymak
- Clarify that colorbars adopt their norm's scaling by default
- Better explain TwoSlopeNorm splits colormap evenly between halves
- Change tick specification to use np.arange for clarity
- Update both cb1 and cb2 to use np.arange(-500, 4001, 500)

Addresses @jklymak review comments

* FIX: Resolve linting errors

- Fix E501: Break long line (line 289) to stay under 88 character limit
- Fix E302: Add missing blank line before function definition

All ruff checks now pass.

* FIX: Remove square brackets from np.arange in set_ticks calls

The set_ticks() method expects a 1D array with shape (N,), but wrapping
np.arange() in square brackets creates a list containing an array with
shape (1, N). This fixes the ValueError by passing the array directly.

* Update galleries/users_explain/colors/colormapnorms.py

Co-authored-by: Jody Klymak <[email protected]>

* FIX: Remove extra blank line before section marker

Precommit linter expects only one blank line before # %% markers.

* FIX: Ensure file ends with single newline

The end-of-file-fixer precommit hook requires files to end
with exactly one newline, not multiple.

* Update galleries/users_explain/colors/colormapnorms.py

Co-authored-by: Jody Klymak <[email protected]>

* Refactor TwoSlopeNorm colorbar example to use loop

- Replace repeated code blocks with a loop as suggested by jklymak
- Iterate over both axes with corresponding titles
- Act on the last colorbar (cb) to set linear scale for right plot
- Reduces code duplication and improves maintainability

* Fix linting errors: line length and inline comment spacing

- Wrap long comment lines to stay within 88 character limit
- Split zip() arguments across lines for better readability
- Add blank line before section marker
- All ruff checks now pass

---------

Co-authored-by: Tim Hoffmann <[email protected]>
Co-authored-by: Jody Klymak <[email protected]>

Author: 3 people

galleries/users_explain/colors/colormapnorms.py

@@ -281,6 +281,32 @@
 cb.set_ticks([-500, 0, 1000, 2000, 3000, 4000])
 plt.show()
 
+# %%
+# Using a linear scale on the colormap
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#
+# By default, colorbars adopt the same axis scaling as their associated norm.
+# For example, for a `.TwoSlopeNorm`, colormap segments are distributed
+# linearly and the colorbar ticks positions are spaced non-linearly (as above,
+# and the left-hand colorbar below). To make the tick spacing linear instead,
+# you can change the scale by calling ``cb.ax.set_yscale('linear')``, as shown
+# in the right-hand colorbar below. The ticks will then be evenly spaced, the
+# colormap will appear compressed in the smaller of the two slope regions.
+
+fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(10, 4))
+divnorm = colors.TwoSlopeNorm(vmin=-500., vcenter=0, vmax=4000)
+
+for ax, title in zip([ax1, ax2],
+                     ['Default: Scaled colorbar', 'Linear colorbar spacing']):
+    pcm = ax.pcolormesh(longitude, latitude, topo, rasterized=True, norm=divnorm,
+                        cmap=terrain_map, shading='auto')
+    ax.set_aspect(1 / np.cos(np.deg2rad(49)))
+    ax.set_title(title)
+    cb = fig.colorbar(pcm, ax=ax, shrink=0.6)
+    cb.set_ticks(np.arange(-500, 4001, 500))
+
+# Set linear scale for the right colorbar
+cb.ax.set_yscale('linear')
 
 # %%
 # FuncNorm: Arbitrary function normalization
@@ -290,6 +316,7 @@
 # `~.colors.FuncNorm` to define your own.  Note that this example is the same
 # as `~.colors.PowerNorm` with a power of 0.5:
 
+
 def _forward(x):
     return np.sqrt(x)