Proposal: auto generate a Figure List

[da5nsy]

Edit: the previous, manually maintained and the eventually outdated list has been deleted, this issue is now a placeholder that we may want to have a list of figures, that is auto-generated.

======

https://github.com/alan-turing-institute/the-turing-way/blob/main/book/website/figures/_figure-list.md

---

• When the book started, it had 17 different figures. As of today, it has roughly 200.
• Despite guidance indicating that all figures should be added to figure_list.md, that file is only infrequently updated.
• It is currently not listed in the TOC.

I argue that instead of updating it, we remove it, since I am not convinced of its utility.

[da5nsy]

This is blocking #2838.

[da5nsy]

Deleted in #2857, for #2838, but will leave this issue open, for further discussion.
See also: discussion on #2857

[bsipocz]

I expect there are a few technical solutions for this, if not, then the new mpl indexing project may also help: https://github.com/matplotlib/matplotlib/wiki/Google-Season-of-Docs-2023:-Proposal

[da5nsy]

Noting this: https://mindtrove.info/jupyter-tidbit-image-gallery/

[JimMadge]

What is it we want to get out of this? Do we just want a page with a table/list of all images in the repository (which isn't quite the same as all of the images in the book)?

Thinking about the style guide positions on alt text and captions, if we did have a list, it could be some sort of structured data including alt text and captions. Could we make a directive to create a figure using that information? It might save duplication of that kind of information and make it easier to ensure all images have alt text and a caption.

Despite guidance indicating that all figures should be added to figure_list.md, that file is only infrequently updated.

I don't think that is surprising. It might be easy to miss the guidance and the book will still build if you ignore it.

Making the process,

1. Add image
2. Edit this yaml file
3. Use the turing-way-figure directive

might enforce good practice at the cost of making contributing less straightforward.

(Plus it would be a lot of work to add all this information for existing figures 😱)

[da5nsy]

Linking #2046 because I think they solve similar problems