[Doc] Updated Hatches API page #27370

pat8901 · 2023-11-26T00:49:13Z

PR summary

This proposed change aims to address the sparsity of information on the hatches API landing page requested in issue #27196. Currently, users landing on this page may see a lack of information on supported hatches. By enhancing the content and linking to the supported hatches it will make it easier for individuals to quickly locate the information they are seeking.

Ashhar-24 was made co-author of this current PR as I took inspiration from Ashhar-24's PR #27203.

closes #27196

PR checklist

"closes #0000" is in the body of the PR description to link the related issue
[N/A] new and changed code is tested
[N/A] Plotting related features are demonstrated in an example
[N/A] New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

Additional Information

In issue #27196 it is requested for an image to be embedded at the top of the API reference page (via the .. plot:: path/to/image directive). Through testing I am unsure if one can use this directive with a path to an image file. The .. image:: directive may be a better option.

Referencing #27357 and https://matplotlib.org/stable/api/sphinxext_plot_directive_api.html I was able to embed the required image using ".. plot::".

In the review please let me know if .. image:: would have been a better choice, and if not, the reasons behind that decision. Your insights will be invaluable for my future pull requests. Thank you.

Co-authored-by: Md Ashhar <mdashhar01@gmail.com>

story645 · 2023-11-27T19:38:47Z

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

pat8901 · 2023-11-28T00:40:16Z

@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!

story645 · 2023-11-28T00:45:19Z

doc/api/hatch_api.rst

+   :alt: Example image showing hatching patterns with level 1 density.
+
+
+For examples using the hatch api refer to: :ref:`sphx_glr_gallery_shapes_and_collections_hatch_style_reference.py`


Looking at the rendered example, jumping into the picture is a bit abrupt so maybe switch- put this as the first sentence, then something introducing the picture (your altext is great)?

No problem! If I understand correctly make line 10 come first then have a sentence introducing the example image, possibly the image alt text. Lastly display the image. Is this close to what you want?

Yup! Exactly

story645

Minor nits but I think almost there.

story645 · 2023-11-30T04:35:50Z

doc/api/hatch_api.rst

@@ -2,6 +2,16 @@
 ``matplotlib.hatch``
 ********************

+For examples using the hatch api refer to: :ref:`sphx_glr_gallery_shapes_and_collections_hatch_style_reference.py`


Suggested change

For examples using the hatch api refer to: :ref:`sphx_glr_gallery_shapes_and_collections_hatch_style_reference.py`

For examples using the hatch api refer to :ref:`sphx_glr_gallery_shapes_and_collections_hatch_style_reference.py`

I don't think it needs the colon?

I agree, I can take it or leave it :) I got rid of it and will submit an update shortly.

story645 · 2023-11-30T04:36:25Z

doc/api/hatch_api.rst

@@ -2,6 +2,16 @@
 ``matplotlib.hatch``
 ********************

+For examples using the hatch api refer to: :ref:`sphx_glr_gallery_shapes_and_collections_hatch_style_reference.py`
+
+Example image showing hatching patterns with level 1 density.


Suggested change

Example image showing hatching patterns with level 1 density.

Example image showing all supported hatching patterns at level 1 density.

Yes! I like that better.

QuLogic · 2023-11-30T07:32:45Z

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

story645 · 2023-11-30T08:11:48Z

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

QuLogic · 2023-11-30T08:53:39Z

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

story645 · 2023-11-30T08:55:52Z

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?

pat8901 · 2023-12-07T23:54:36Z

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

story645

Sorry, didn't look at the alt text closely the first time. Otherwise I think it's good.

story645 · 2023-12-08T06:19:28Z

doc/api/hatch_api.rst

+
+.. image:: /gallery/shapes_and_collections/images/sphx_glr_hatch_style_reference_001.png
+   :align: center
+   :alt: Example image showing all supported hatching patterns at level 1 density.


Sorry I didn't catch this earlier, but I think the alt text here should be more descriptive
" 8 squares, each showing the pattern corresponding to the hatch symbol:
hatch pattern / with square showing right leaning diagonals, \ is left leaning diagonals, | is vertical lines, - is horizontal lines, + is a grid, X is a grid rotated 90 degrees, o is small unfilled circles, O is large unfilled circles, . is small filled circles, and * is 5 point stars

timhoffm · 2023-12-08T09:12:31Z

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 the hatches_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 like https://github.com/matplotlib/matplotlib/blob/main/doc/api/axes_api.rst

story645 · 2023-12-08T14:21:53Z

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.

story645 · 2023-12-13T19:52:44Z

@pat8901 last steps are

move the docs to hatch.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.

story645 · 2024-08-14T21:39:10Z

@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.

story645 · 2025-02-18T20:38:38Z

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

[Doc] Updated Hatches API page

bd60fd5

Co-authored-by: Md Ashhar <mdashhar01@gmail.com>

pat8901 mentioned this pull request Nov 26, 2023

[CI]: PR Greetings is failing due to node.js error #27371

Closed

pat8901 added 2 commits November 27, 2023 17:52

Addressed review feedback

852e66c

Fixed image path

5433b2f

story645 added Documentation: API files in lib/ and doc/api topic: hatch labels Nov 28, 2023

story645 added this to the v3.8-doc milestone Nov 28, 2023

story645 reviewed Nov 28, 2023

View reviewed changes

Addressed review feedback v2

241d45a

story645 reviewed Nov 30, 2023

View reviewed changes

Addressed review feedback v3

1c84887

story645 requested changes Dec 8, 2023

View reviewed changes

story645 mentioned this pull request Dec 18, 2023

[DOC]: usage docs content guidelines #26389

Draft

story645 mentioned this pull request Aug 14, 2024

Added link and image to matplotlib.hatch API Page #27203

Closed

5 tasks

story645 mentioned this pull request Feb 18, 2025

[Doc] Added images of hatches to hatch API page #29644

Merged

5 tasks

story645 closed this Feb 18, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Doc] Updated Hatches API page #27370

[Doc] Updated Hatches API page #27370

pat8901 commented Nov 26, 2023

story645 commented Nov 27, 2023 •

edited

Loading

pat8901 commented Nov 28, 2023

story645 Nov 28, 2023

pat8901 Nov 28, 2023

story645 Nov 28, 2023 •

edited

Loading

story645 left a comment

story645 Nov 30, 2023

pat8901 Nov 30, 2023

story645 Nov 30, 2023

pat8901 Nov 30, 2023

QuLogic commented Nov 30, 2023

story645 commented Nov 30, 2023

QuLogic commented Nov 30, 2023

story645 commented Nov 30, 2023

pat8901 commented Dec 7, 2023

story645 left a comment

story645 Dec 8, 2023

timhoffm commented Dec 8, 2023

story645 commented Dec 8, 2023

story645 commented Dec 13, 2023

story645 commented Aug 14, 2024

story645 commented Feb 18, 2025

		:alt: Example image showing hatching patterns with level 1 density.


		For examples using the hatch api refer to: :ref:`sphx_glr_gallery_shapes_and_collections_hatch_style_reference.py`

	Example image showing hatching patterns with level 1 density.
	Example image showing all supported hatching patterns at level 1 density.

[Doc] Updated Hatches API page #27370

[Doc] Updated Hatches API page #27370

Conversation

pat8901 commented Nov 26, 2023

PR summary

PR checklist

Additional Information

story645 commented Nov 27, 2023 • edited Loading

pat8901 commented Nov 28, 2023

story645 Nov 28, 2023

Choose a reason for hiding this comment

pat8901 Nov 28, 2023

Choose a reason for hiding this comment

story645 Nov 28, 2023 • edited Loading

Choose a reason for hiding this comment

story645 left a comment

Choose a reason for hiding this comment

story645 Nov 30, 2023

Choose a reason for hiding this comment

pat8901 Nov 30, 2023

Choose a reason for hiding this comment

story645 Nov 30, 2023

Choose a reason for hiding this comment

pat8901 Nov 30, 2023

Choose a reason for hiding this comment

QuLogic commented Nov 30, 2023

story645 commented Nov 30, 2023

QuLogic commented Nov 30, 2023

story645 commented Nov 30, 2023

pat8901 commented Dec 7, 2023

story645 left a comment

Choose a reason for hiding this comment

story645 Dec 8, 2023

Choose a reason for hiding this comment

timhoffm commented Dec 8, 2023

story645 commented Dec 8, 2023

story645 commented Dec 13, 2023

story645 commented Aug 14, 2024

story645 commented Feb 18, 2025

story645 commented Nov 27, 2023 •

edited

Loading

story645 Nov 28, 2023 •

edited

Loading