Cookbook recipe examples

[digitaldogsbody]

Cookbook recipes that can be made into examples of how to use the iiif-prezi3 library.

If you'd like to work on one, please claim it by comment (or editing this issue) and then:

1. Create a branch from the main branch - git checkout main && git pull && git checkout -b recipe_0024
2. Manually checkout the appropriate skeleton file from the cookbook_skeletons branch (this is necessary to avoid committing all the skeletons to the branch which will be merged) - git checkout cookbook_skeletons docs/recipes/0024-book-4-toc.md
   • This should have copied the skeleton file to your new branch
   • For a list of the filenames see https://github.com/iiif-prezi/iiif-prezi3/tree/cookbook_skeletons/docs/recipes
3. Check that the manifest link is correct and update if necessary. I autogenerated these skeletons from the names of the directories in the recipes repo, so sometimes <recipe_url>/manifest.json is not actually correct - see https://github.com/iiif-prezi/iiif-prezi3/blob/cookbook/docs/recipes/0010-book-2-viewing-direction.md for an example.
4. Create the example code, remembering to print it at the end
   • The example code should go into the docs/recipes/scripts subdirectory
   • Files should be named XXXX-recipe-shortname-methodX.py for single-example recipes, and XXXX-recipe-shortname-exampleX-methodX.py (or XXXX-recipe-shortname-usecaseX-methodX in the rare situations where "Use Case" is used in the recipe instead of "Example) for multi-example recipes.
   • If in doubt about the naming, have a look at the existing files and feel free to ping Mike in the Slack channel.
5. Add the transclusion link to the example code in the recipe Markdown file - see an existing filefor an example
6. Run your code in a Python environment with the library installed and do a check that the generated JSON matches the appropriate example from the cookbook.
   • The utils/test_cookbook.py script can help with this.
   • Invoke by cd utils (necessary until Cookbook checker script only works from utils directory #174 is resolved) and then python test_cookbook.py -v --fail-missing ../docs/recipes/XXXX-recipe-shortname.md
   • This will also be run on PR by the CI setup, but running it locally can help catch any errors in advance.
7. Commit your recipe example and pull request your branch
8. Once merged, tick the recipe off as complete below

Recipes:

• 0001 Simplest Manifest - Single Image File (docs/recipes/0001-mvm-image.md) - @digitaldogsbody
• 0002 Simplest Manifest - Audio (docs/recipes/0002-mvm-audio.md) - @digitaldogsbody
• 0003 Simplest Manifest - Video (docs/recipes/0003-mvm-video.md) - @digitaldogsbody
• 0004 Image and Canvas with Differing Dimensions (docs/recipes/0004-canvas-size.md) - @digitaldogsbody
• 0005 Support Deep Viewing with Basic Use of a IIIF Image Service (docs/recipes/0005-image-service.md) - @digitaldogsbody
• 0006 Internationalization and Multi-language Values (docs/recipes/0006-text-language.md) - @digitaldogsbody
• 0007 Embedding HTML in descriptive properties (docs/recipes/0007-string-formats.md) - @digitaldogsbody
• 0008 Rights statement (docs/recipes/0008-rights.md) - @digitaldogsbody
• 0009 Simple Manifest - Book (docs/recipes/0009-book-1.md) - @digitaldogsbody
• 0010 Viewing direction and Its Effect on Navigation (docs/recipes/0010-book-2-viewing-direction.md) - @digitaldogsbody
• 0011 Book 'behavior' Variations (continuous, individuals) (docs/recipes/0011-book-3-behavior.md) - @digitaldogsbody
• 0013 "Load a Preview Image Before the Main Content" (docs/recipes/0013-placeholderCanvas.md)
• 0014 "Audio Presentation with Accompanying Image" (docs/recipes/0014-accompanyingcanvas.md)
• 0015 Begin playback at a specific point - Time-based media (docs/recipes/0015-start.md) - @digitaldogsbody
• 0017 Providing Access to Transcript Files of A/V Content (docs/recipes/0017-transcription-av.md) - @digitaldogsbody
• 0019 HTML in Annotations (docs/recipes/0019-html-in-annotations.md) - @digitaldogsbody
• 0021 Simple Annotation — Tagging (docs/recipes/0021-tagging.md) - @digitaldogsbody
• 0024 Table of Contents for Book Chapters (docs/recipes/0024-book-4-toc.md) - @digitaldogsbody
• 0026 Table of Contents for A/V Content (docs/recipes/0026-toc-opera.md)
• 0029 Metadata on any Resource (docs/recipes/0029-metadata-anywhere.md)
• 0030 Multi-volume Work with Individually-bound Volumes (docs/recipes/0030-multi-volume.md)
• 0031 Multiple Volumes in a Single Bound Volume (docs/recipes/0031-bound-multivolume.md)
• 0033 Multiple Choice of Images in a Single View (Canvas) (docs/recipes/0033-choice.md)
• 0035 Foldouts, Flaps, and Maps (docs/recipes/0035-foldouts.md)
• 0036 Composition from Multiple Images (docs/recipes/0036-composition-from-multiple-images.md)
• 0040 Image Rotation Two Ways (docs/recipes/0040-image-rotation-service.md)
• 0046 Providing Alternative Representations (docs/recipes/0046-rendering.md)
• 0047 Linking to Web Page of an Object (docs/recipes/0047-homepage.md)
• 0053 Linking to Structured Metadata (docs/recipes/0053-seeAlso.md)
• 0064 Table of Contents for Multiple A/V Files on a Single Canvas (docs/recipes/0064-opera-one-canvas.md)
• 0065 Table of Contents for Multiple A/V Files on Multiple Canvases (docs/recipes/0065-opera-multiple-canvases.md)
• 0068 A basic newspaper (docs/recipes/0068-newspaper.md)
• 0074 Using Caption and Subtitle Files in Multiple Languages with Video Content (docs/recipes/0074-multiple-language-captions.md)
• 0117 Image Thumbnail for Manifest (docs/recipes/0117-add-image-thumbnail.md)
• 0118_multivalue Displaying Multiple Values with Language Maps (docs/recipes/0118_multivalue.md) - @giacomomarchioro
• 0139 Represent Canvas Fragment as a Geographic Area in a Web Mapping Client (docs/recipes/0139-geolocate-canvas-fragment.md)
• 0154 id: 154 (docs/recipes/0154-geo-extension.md)
• 0202 Load Manifest Beginning with a Specific Canvas (docs/recipes/0202-start-canvas.md)
• 0219 Using Caption and Subtitle Files with Video Content (docs/recipes/0219-using-caption-file.md)
• 0230 Navigation by Chronology (docs/recipes/0230-navdate.md) - @digitaldogsbody
• 0231 Transcripts, Captions, and Subtitles - General Considerations (docs/recipes/0231-transcript-meta-recipe.md)
• 0232 "Implementation discussion: Thumbnails on Canvases" (docs/recipes/0232-image-thumbnail-canvas.md)
• 0234 Acknowledge Content Contributors (docs/recipes/0234-provider.md)
• 0240 Locate Multiple Canvases on a Web Map (docs/recipes/0240-navPlace-on-canvases.md)
• 0258 Tagging with an External Resource (docs/recipes/0258-tagging-external-resource.md)
• 0261 Annotation with a Non-Rectangular Polygon (docs/recipes/0261-non-rectangular-commenting.md)
• 0266 Simplest Annotation (docs/recipes/0266-full-canvas-annotation.md)
• 0269 Embedded or referenced Annotations (docs/recipes/0269-embedded-or-referenced-annotations.md)
• 0299 Addressing a Spatial Region (docs/recipes/0299-region.md)

[glenrobson]

@giacomomarchioro to look at a way of embedding a python file in markdown so we can unit test them to check if they match the recipe.

[giacomomarchioro]

That's very well done!
The only problem I found with mkdocs is that the headings are generating multiple elements in the table of contents, I don't know there is an easy fix, maybe a table could improve the layout?

Regarding the reuse of the recipes, I have tried a different approach using snippets.

I have started a discussion here #138.

[digitaldogsbody]

I have reformatted the existing recipes to use the table approach as in your example, I agree it looks cleaner (PR is here: #149).

I also like the snippet approach, and have adopted that also in the same PR. Next up is writing a testing library and then updating some existing recipes now that the latest skeleton is merged (i.e 0013,0014, and 0017 should now be possible)

[digitaldogsbody]

Testing library added to the above PR + rewriting some of the existing recipes to be cleaner and adding 0017 now that it is possible

[glenrobson]

Mike to add note about needing method1 in the script filename.

[digitaldogsbody]

Instructions above rewritten to cover all the changes to the process

[markpbaggett]

Hello,

I've added a few recipe examples as pull requests:

• Recipe 198
• Recipe 197
• Recipe 196

Let me know if I can do something else to help here.