From bc82744bca3efe8e6c5f79ace5fb5e680011da21 Mon Sep 17 00:00:00 2001
From: Patrick Seitz <seitzpr@gmail.com>
Date: Sat, 25 Nov 2023 18:36:45 -0500
Subject: [PATCH] [Doc] Updated Hatches API page

Co-authored-by: Md Ashhar <mdashhar01@gmail.com>
Co-authored-by: hannah <story645@gmail.com>
Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

added a hatch mpl_type that links to the hatch reference docs
---
 doc/_embedded_plots/hatch_classes.py          | 28 +++++++++++++++++++
 .../hatch_style_reference.py                  |  2 ++
 lib/matplotlib/hatch.py                       | 19 ++++++++++++-
 lib/matplotlib/sphinxext/roles.py             |  1 +
 4 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 doc/_embedded_plots/hatch_classes.py

diff --git a/doc/_embedded_plots/hatch_classes.py b/doc/_embedded_plots/hatch_classes.py
new file mode 100644
index 000000000000..cb9cd7d4b356
--- /dev/null
+++ b/doc/_embedded_plots/hatch_classes.py
@@ -0,0 +1,28 @@
+import matplotlib.pyplot as plt
+from matplotlib.patches import Rectangle
+
+fig, ax = plt.subplots()
+
+pattern_to_class = {
+    '/': 'NorthEastHatch',
+    '\\': 'SouthEastHatch',
+    '|': 'VerticalHatch',
+    '-': 'HorizontalHatch',
+    '+': 'VerticalHatch + HorizontalHatch',
+    'x': 'NorthEastHatch + SouthEastHatch',
+    'o': 'SmallCircles',
+    'O': 'LargeCircles',
+    '.': 'SmallFilledCircles',
+    '*': 'Stars',
+}
+
+for i, (hatch, classes) in enumerate(pattern_to_class.items()):
+    r = Rectangle((0.1, i+0.5), 0.8, 0.8, fill=False, hatch=hatch*2)
+    ax.add_patch(r)
+    h = ax.annotate(f"'{hatch}'", xy=(1.2, .5), xycoords=r,
+                    family='monospace', va='center', ha='left')
+    ax.annotate(pattern_to_class[hatch], xy=(1.5, .5), xycoords=h,
+                family='monospace', va='center', ha='left', color='tab:blue')
+
+ax.set(xlim=(0, 5), ylim=(0, i+1.5), yinverted=True)
+ax.set_axis_off()
diff --git a/galleries/examples/shapes_and_collections/hatch_style_reference.py b/galleries/examples/shapes_and_collections/hatch_style_reference.py
index 724abde051b4..064eec7d3e4e 100644
--- a/galleries/examples/shapes_and_collections/hatch_style_reference.py
+++ b/galleries/examples/shapes_and_collections/hatch_style_reference.py
@@ -1,4 +1,6 @@
 """
+.. _hatch_def:
+
 =====================
 Hatch style reference
 =====================
diff --git a/lib/matplotlib/hatch.py b/lib/matplotlib/hatch.py
index 0cbd042e1628..6ce68a275b4e 100644
--- a/lib/matplotlib/hatch.py
+++ b/lib/matplotlib/hatch.py
@@ -1,4 +1,21 @@
-"""Contains classes for generating hatch patterns."""
+"""
+Module for generating hatch patterns.
+
+For examples of using the hatch API, see
+:ref:`sphx_glr_gallery_shapes_and_collections_hatch_style_reference.py`.
+
+The following hatching patterns are available, shown here at level 2 density:
+
+.. plot:: _embedded_plots/hatch_classes.py
+    :include-source: false
+    :alt:
+        8 squares, each showing the pattern corresponding to the hatch symbol:
+        symbol '/' makes right leaning diagonals, '\\' makes left leaning diagonals,
+        '|' makes vertical lines, '-' makes horizontal lines, '+' makes a grid,
+        'X' makes a grid rotated 90 degrees, 'o' makes small unfilled circles,
+        'O' makes large unfilled circles, '.' makes small filled circles, and '*' makes
+        a star with 5 points
+"""
 
 import numpy as np
 
diff --git a/lib/matplotlib/sphinxext/roles.py b/lib/matplotlib/sphinxext/roles.py
index 301adcd8a5f5..c3e57ebc3aec 100644
--- a/lib/matplotlib/sphinxext/roles.py
+++ b/lib/matplotlib/sphinxext/roles.py
@@ -125,6 +125,7 @@ def _mpltype_role(name, rawtext, text, lineno, inliner, options=None, content=No
     mpltype = text
     type_to_link_target = {
         'color': 'colors_def',
+        'hatch': 'hatch_def',
     }
     if mpltype not in type_to_link_target:
         raise ValueError(f"Unknown mpltype: {mpltype!r}")