I believe the mpl_type link should point to the hatch style reference.

Amending the matplotlib.hatch API page is okish. I'd like to point out though that the hatch classes defined there cannot be used by the user. AFAICS the only public API to create hatches is through hatch patterns. In that sense matplotlib.hatch is an implementation detail, and we could even make it private. IMHO documentation on the API page should rather connect the visual to the classes, e.g.

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()):
    ax.add_patch(Rectangle((0.1, i+0.5), 0.8, 0.8, fill=False, hatch=hatch*2))
    ax.text(1.3, i+0.9, f"'{hatch}'", family='monospace', va='center')
    ax.text(2, i+0.9, pattern_to_class[hatch], family='monospace', va='center', color='tab:blue')
ax.set(xlim=(0, 5), ylim=(0, i+1.5), yinverted=True)
ax.set_axis_off()

So like your table, gonna adopt that.

In that sense matplotlib.hatch is an implementation detail, and we could even make it private.

I think the reason not to is for helper classes for custom hatches #20690

FYI: I've added a minor position tweak to the above code.

Um, I just used annotate

 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()

Ok, I have a it's possibly documented somewhere question, but does the plot directive not work in the API docs? I pushed changes in the latest commit just in case I'm doing something silly.

Interesting. I don't think we have the plot directive in any other module docstring, but we have it in method docstrings and there it works, e.g. https://output.circle-artifacts.com/output/job/4778f46c-549d-46ab-8d66-29dd2131e7e8/artifacts/0/doc/build/html/api/_as_gen/matplotlib.axes.Axes.margins.html#matplotlib.axes.Axes.margins.

Just as a note Sphinx 8.2 was released yesterday. It could be that there is a regression, but again, the method docstring works (I've intentionally picked your doc build here in the link above.

So the answer is I was doing something silly - plot_formats is a config variable and not an option parameter 🤦‍♀️

And that doesn't lead to an error or at least warning? AFAIR Sphinx built clearly.

And that doesn't lead to an error or at least warning? AFAIR Sphinx built clearly.

Nope 😭