Doc: Tracking Issue for Graphics

[MarsBarLee]

Hi all, this is a tracking issue for adding and updating the graphics in the Numpy documentation. If you see any graphics you think deserve an update, let us know here!

Graphical elements that need an update:

• Outdated information, such as deprecated functions
• Hard-to-read text, such as small, blurry or handwritten text
• Cluttered or messy elements

Here's an example of a graphic we think deserve an update.
A flowchart for Array types for scalars

It does the job right now, but some text is cut off and some content is outdated.

If you're working on a documentation contribution, consider adding graphics! You can post here with your issue or PR. @melissawm and I can suggest new diagrams or digitize your existing hand-drawn diagram. We can also add diagrams after merging if you prefer that workflow.

Here's an example of an update I did with a contributor's PR.

We are also looking to standardize the file format and style of the graphics to make it more accessible for readers and easier for contributors to edit in the future.
Let us know if you have any thoughts or suggestions!

File format: SVG (scalable vector graphics)

• Small, scalable and text can be edited without needing graphic software.
• SVG text can also be read by screen-readers, unlike PNG or JPG

Design principle: Material Design

• Clean, easy to understand, and fits with rest of the Numpy website design

Editing SVGs:

• Edit the SVG code directly, which is in the XML format, similar to HTML
• Use open-source graphic software such as Boxy SVG Editor, Inkscape or GIMP
• Programatically create SVGs with Graphviz or Flowchart.js

[melissawm]

Thanks, @MarsBarLee !

I'd like to add #17517 as a relevant issue.

[8bitmp3]

Here's an example of an update I did with a contributor's PR.

This is great @MarsBarLee

[MarsBarLee]

Based on the discussion in the recent Numpy Documentation, I'll add GIMP as an open-source SVG editor.

Graphviz was also recommended for people who want to programmatically create graphics instead of starting with graphic software. I'm just not sure if and where we keep its file format .gv for future use, or if we only keep the exported SVG.

@8bitmp3 brought up color accessibility, which is something I'll look into.

[8bitmp3]

@MarsBarLee What do you think of these accessibility (a11y) sources:

• https://www.writethedocs.org/blog/newsletter-august-2017/#accessible-docs-colorblindness-edition
• https://accessibility.psu.edu/images/charts/
• https://apastyle.apa.org/style-grammar-guidelines/tables-figures/colors
• https://www.writethedocs.org/blog/newsletter-november-2020/#all-about-accessibility-and-inclusivity
• Presentations: by @heyawhite (👋 ) last year https://www.writethedocs.org/videos/portland/2020/moving-beyond-empathy-a11y-in-documentation-alexandra-white + https://www.writethedocs.org/videos/prague/2018/a11y-friendly-documentation-carolyn-stransky

---

From https://accessibility.psu.edu/images/charts/:

• Bart charts:

• Line charts:

[cooperrc]

Based on the discussion in the recent Numpy Documentation, I'll add GIMP as an open-source SVG editor.

Gimp is great, but it is for bitmap editing. I like the idea of using Inkscape. Inkscape supports Python scripting. @rossbar mentioned it would be nice to have reproducible/customizable figures (I was assuming script-generated) when possible. Inkscape might provide a middle ground in the respect.

Blender is another svg editor with a full Python environment, but the files are binary and the outputs are usually bitmaps (without customizing too much).

Graphviz was also recommended for people who want to programmatically create graphics instead of starting with graphic software. I'm just not sure if and where we keep its file format .gv for future use, or if we only keep the exported SVG.

Cool, I hadn't seen this one before. It looks great for flow charts. It might be good to have a "image-source" location to store files like *.gv, but keep the docs in a consistent *.svg format in an "images" folder. The *.xml format for svg does support comments and metadata. If there are build files, maybe we could add them in a consistent metadata location for the xml file.

[MarsBarLee]

Gimp is great, but it is for bitmap editing

@cooperrc
It is, but looking briefly at its documentation for SVGs it says that if the Path tool is used, GIMP can export these Paths as an SVG. Other tools like Paintbrush are for bitmap editing.

If an SVG file is imported, it will appear as Paths and can be edited.

But Inkscape or other vector software is recommended for further editing. But maybe GIMP can work for basic changes for someone most familiar with GIMP?

But I haven't used GIMP for this yet, this is based on my experience in SVGs and Paths in Photoshop, another bitmap editor.

There's also many more resources for making vectors in Inkscape than GIMP, so I think we should encourage Inkscape anyway.

[cooperrc]

It is, but looking briefly at its documentation for SVGs it says that if the Path tool is used, GIMP can export these Paths as an SVG. Other tools like Paintbrush are for bitmap editing.

Cool, thanks for the link! I use and recommend Inkscape for everything, so I guess I haven't explored Gimp enough.

[rossbar]

It might be good to have a "image-source" location to store files like *.gv, but keep the docs in a consistent *.svg format in an "images" folder.

I think keeping just the outputs is fine. Storing "source" and "output" files without actually using the source to generate the output is a maintenance burden, as changes to either the graphic or the source require changes to be made to the other. Of course, it would be relatively straightforward to generate figures from graphviz during the build process (via pygraphviz for sphinx or graphviz itself for hugo, for example), but that would be a wishlist item, and shouldn't be a blocker to improving the graphics!

[Mukulikaa]

SVGs are not supported by the Latex build yet, causing problems for the PDF build of the documentation (see #20690 (comment)). Note that only the User and Reference guides are built as PDFs so I think we'll only need to figure out what to do about images in them.

[MarsBarLee]

Thanks @Mukulikaa for replacing the SVGs with PNG! I'm not sure if latex cannot handle any SVGs or only handle SVGs with bounding boxes. If the latter, we can add a section to the future graphics guidelines to save SVGs with bounding boxes.

[Mukulikaa]

Hi @MarsBarLee, according to the Sphinx docs, the Latex builder doesn't support SVGs at all. @rossbar suggested trying out sphinx.ext.imgconverter. This requires Imagemagick to be installed locally.