docs(IC): convert ImageCache doc example into a compiling test

[FaisalXL]

closes the ImageCache (doc) part of #3992.

Converts the ImageCache chapter's doc example (src/doc/imagecache.rst) from a hardcoded text into compiling C++ and Python tests. Referenced from the docs via literalinclude.

changes:

• testsuite/docs-examples-cpp/src/docs-examples-imagecache.cpp and testsuite/docs-examples-python/src/docs-examples-imagecache.py: filled in the example1() stub with a real example exercising ImageCache::create/attribute/get_imagespec/get_pixels/get_tile/tile_pixels/release_tile/destroy.
• src/doc/imagecache.rst: replaced the raw snippet with .. tabs:: /.. literalinclude:: for both languages
• testsuite/docs-examples-{cpp,python}/ref/out*.txt: updated golden output for the new resolution is 512x384 line the example now prints.

Notes for reviewers

The original doc snippet no longer compiled against current main, fixed following points:

• ImageCache::create()/destroy() moved to std::shared_ptr(api: image_span-ify ImageCache and TextureSystem #4783).
• get_pixels(..., const span<T>&, ...) appears to have a bug: it builds an image_span<T> internally but passes the original span<T> argument to as_image_span_writable_bytes() instead of the image_span it just built, so it doesn't compile. currently worked around by calling the image_span<T> overload directly.

Full test suite run locally: 124/147 passing. I confirmed that no failures were introduced by this change

Assisted-by: Claude sonnet 5 was used in understanding the issue and the codebase

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: FaisalXL / name: Faisal (00679ad)

[lgritz]

get_pixels(..., const span<T>&, ...) appears to have a bug: it builds an image_span<T> internally but passes the original span<T> argument to as_image_span_writable_bytes() instead of the image_span it just built, so it doesn't compile. currently worked around by calling the image_span<T> overload directly.

Oh, good catch! And THIS is exactly why we have this whole exercise of converting examples in the docs (that are just text) into code that's actually run in the testsuite -- it both finds bugs in the docs example (like the std::shared_ptr issue you fixed), and also gives us better test coverage of the APIs that can catch real internals problems like the get_pixels bug you mention.

So... do you want to take a stab at fixing the real get_pixels bug? (Could be in a different PR if you want.)

[lgritz]

@FaisalXL Ping on this. It's so close to being ready to merge.

Required:

• An extremely minor formatting fix caught by the clang-format test (click on that failed test to see the part of the log that tells you exactly what to fix.

Optional:

• Let me know what you want to do about the get_pixels problem you noticed: (a) you fix it as part of this PR, (b) you fix it in a subsequent PR, (c) somebody else fixes later (though preferably with you submitting a description of the problem as an Issue so we don't forget).

[FaisalXL]

@lgritz my apologies on the delay, just pushed the fix (formatting) and rebased to resolve the minor conflict from #5346 (folded in the new per-chapter print statements alongside my output line)

on the other get_pixels bug, I'll file it as a separate issue!

[lgritz]

LGTM, thanks!