Example in Documentation (updated rev1)

[42sol-eu]

added the first three samples for the examples (example_1.rst)

1. Is this the structure (chapter/images) helpful for the users
2. Is something too much or too less?
3. Look into the helper scripts docs/assets/examples named create_thumbnail_images.py and create_rst.py

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (ec4171e) 96.11% compared to head (6e6233c) 96.11%.

Additional details and impacted files

@@           Coverage Diff           @@
##              dev     #490   +/-   ##
=======================================
  Coverage   96.11%   96.11%           
=======================================
  Files          24       24           
  Lines        7461     7461           
=======================================
  Hits         7171     7171           
  Misses        290      290           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[42sol-eu]

there is an benchy_v2024.py that implements a yaml-doc-string to fill the example_1.rst blocks with the helper script create_rst.py

there is a README.md in ./examples documenting the steps (most of them are now automated in create_rst.py)

[gumyr]

If I understand correctly, the create_rst.py script would primarily be used during the batch process of converting all of the existing examples to this new format. Therefore, I wonder if it should be part of the build123d repo? Similarly with create_thumbnail_image.py, I would typically use imagemag for this type of thing (it work on batches of files).

With the benchy there are several images but it looks like only the first appears in docs. Since creation is done manually, I wonder if the extra work of creation is justified.

What if we just start with the rst files and associated images contained in the PR? This should help get a feel for what the docs will look like and allow others to provide feedback.

[42sol-eu]

ok. I can remove the helper python scripts and the yaml files.

About the Benchy you are right, I missed the example with more images - will be rectified.

[42sol-eu]

@gumyr followed your lead.

• removed the helper scripts
• inserted the missing benchy images in a "poor mans gallery" hidden detail section
• removed too detailed information (author, history ...)

Content-wise Concepts

1. Have a quick overview of an example with a main image to show the model
2. Include information about builder and algebra mode (symbols)
3. Short overview of the example in a paragraph
4. No too detailed information
5. OPTIONAL: More images in a gallery if it makes sense (maybe not for the benchy - just to show how it would work)
6. OPTIONAL: (to be discussed) add the examples code -> PRO: this really helps in searching for example Mesher it would also find the example benchy.py which gives the user a great tool to quickly find a code snippet in context of the examples

Process-wise Concepts
7. Description how to add examples (in the example_1.rst AND a readme.md)
8. ˜˜OPTIONAL: support the developer/contributer to quickly generate RST from command line (REMOVED FROM PULL REQUEST)˜˜

Feel free to ask me if I should present the concept in more depth