through testing I am unsure if one can use this directive with a path to an image file

Yes, and that was my intent with that suggestion. The following should work:

..plot::gallery/shapes_and_collections/hatch_style_reference.py

if it doesn't b/c the example makes too many images then use..image

@story645 Yes you are correct using.. plot:: led to too many examples. I opted for.. image:: and changed the code accordingly.
Let me know if there is anything else I need to do. Thank you!

Hmm, should this go here, or in the module description inlib/matplotlib/hatches.py?

Figured here b/c it gets rendered at the top of the reference page & also I thought this sorta thing was the point of the /API pages?

https://output.circle-artifacts.com/output/job/6428217d-4dd4-4c9d-bf62-02905d884afc/artifacts/0/doc/build/html/api/hatch_api.html

The top of that file appears there too; it's the "Contains classes for generating hatch patterns." line.

Yeah I know, what I'm trying to say/ask is why the module page vs the API page since they get rendered together in the docs?

@QuLogic@story645 Is there any update on this? Any thing I need to do?

Yeah I know, what I'm trying to say/ask is why the module page vs the API page since they get rendered together in the docs?

We currently don't have a strict policy on this. However, I suggest that we try to keep most API pages free of content, i.e. as thehatches_api.rst has been for now. As long as you only want a short description at the top, that should go into the module docstring. Advantages are:

• api.rst pages are purely technical definitions of layout. If we want to change that in the future, it's simpler than having to search through content.
• The content is in one place. You know where to look and there is no danger of duplicate or incongruent content because part is written in the api.rst and part is written in the module docstring (both are rendered in the HTML page).
• The type of information on top of the API page is exactly what should be in a module docstring. When actually writing it into the module docstring, there's less danger that the API pages grow tutorial style or lengthy examples.

I propose to make the a general rule. Of course, there will be exceptions for a few more involved API pages likehttps://github.com/matplotlib/matplotlib/blob/main/doc/api/axes_api.rst

propose to make the a general rule.

I'm not opposed/your reasoning makes sense to me, but then I'd like it documented in the "writing docs" section of dev docs if it's gonna be policy.

@pat8901 last steps are

• move the docs tohatch.py as suggested by@timhoffm
• consider my suggested alt text

@timhoffm can I spin your comment off into an issue? I'll make sure to put a giant "Not for new contributors" disclaimer.

@pat8901 hi, sorry for the delay, any chance you have bandwith to finish this? otherwise I'll pick it up to finish in a separate commit.

Superceded by#29644 cause this was made to main so I can't push changes, but I kept the authorship from here.