Update example for converting DLC project to benchmark (v2) (#49)

* Add tree utility for displaying directory structures

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add frames_to_poseinterface and fix predictions output suffix

Add frames_to_poseinterface utility to copy and rename frame images
according to filenames in a COCO JSON file. Also fix the output
filename of predictions_to_poseinterface to use _cliplabels.json
suffix matching the naming convention.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add lightweight DLC project fixture for testing and examples

Adds a minimal DLC project under tests/data/dlc/ with 2 sessions,
each containing a small (100 frames) video, placeholder PNGs, and
annotation/prediction CSVs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add convert_dlc_to_benchmark sphinx-gallery example

Replace SWC-plusmaze_to_benchmark example with a new end-to-end
example showing how to convert a DLC project to the poseinterface
benchmark dataset format. Update sphinx-gallery config to execute
examples, add API entries for new functions, and add jupyter and
matplotlib dependencies.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Pin movement>=0.16.0 and update supported Python versions to 3.12-3.14

* updated conversion example

* add workflow image to the conversion example

* add API reference entry for `predictions_to_poseinterface`

* Fix predictions_to_poseinterface kwargs in example after rebase

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix typo

* Rename frames_to_poseinterface params to input_dir/output_dir

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* temporarily try on real data and add provenance

* switch back to using small fixture in example

* remove duplicate prediction_to_interface entry in API index

* Apply suggestions about frames_to_poseinterface

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

* Apply suggestions about tree

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

* Apply suggestions about simplifying tests for tree

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

* Fix missing warnings import and add test for partial frame match

Add `import warnings` to io.py (needed after review suggestion
introduced `warnings.warn`), update error message match in existing
test, and add a new test for the partial-match warning path.
Includes minor formatting fixes from ruff-format.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Apply suggestions about gallery example

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

* add myst target for folder structure

* Suppress spurious cell output in provenance example cell

The write_text() return value (byte count) was rendered as cell
output by sphinx-gallery. Use capture_repr = () to suppress it.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Enable always_use_bars_union for modern union type rendering

Renders `Path | str` instead of `Union[Path, str]` in API docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* replace image placeholders with real images

* add custom example thumbnail

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

Author: 3 people

docs/source/_static/DLC_to_poseinterface_worklow.svg

@@ -2,7 +2,7 @@ API
 ===
 
 io
-----
+--
 
 .. currentmodule:: poseinterface.io
 
@@ -11,15 +11,30 @@ io
     :template: function.rst
 
     annotations_to_poseinterface
-    video_to_poseinterface
+    frames_to_poseinterface
     predictions_to_poseinterface
+    video_to_poseinterface
+
 
 clips
 -----
+
 .. currentmodule:: poseinterface.clips
 
 .. autosummary::
     :toctree: api_generated
     :template: function.rst
 
     extract_clip
+
+
+utils
+-----
+
+.. currentmodule:: poseinterface.utils
+
+.. autosummary::
+    :toctree: api_generated
+    :template: function.rst
+
+    tree

docs/source/_static/project_icon.png

@@ -17,6 +17,7 @@ We mark requirements with italicised *keywords* that should be interpreted as de
 
 The current scope is limited to **single-animal pose estimation** from a **single camera view**. Support for multi-camera setups is planned for a future version.
 
+(target-dataset-folder-structure)=
 ## Folder structure
 
 :::{note}

docs/source/api_index.rst

@@ -76,6 +76,9 @@
 autosummary_generate = True
 autodoc_default_flags = ["members", "inherited-members"]
 
+# sphinx-autodoc-typehints configuration
+always_use_bars_union = True
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
@@ -86,6 +89,12 @@
     "**/includes/**",
     # Auto-generated by sphinx-gallery; contains dangling refs to ignored examples
     "sg_execution_times.rst",
+    # exclude .py and .ipynb files in examples generated by sphinx-gallery
+    # this is to prevent sphinx from complaining about duplicate source files
+    "auto_examples/*.ipynb",
+    "auto_examples/*.py",
+    "auto_examples/**/*.ipynb",
+    "auto_examples/**/*.py",
 ]
 
 # -- Options for HTML output -------------------------------------------------
@@ -138,14 +147,12 @@
 }
 
 # -- Sphinx-Gallery configuration -------------------------------------------
+
 sphinx_gallery_conf = {
     "examples_dirs": ["../../examples"],
     "gallery_dirs": ["auto_examples"],
-    # Patterns of example filenames to ignore (not built or shown in gallery).
-    # Use this for scripts that depend on data/resources not available in CI
-    # or on the developer's machine (e.g. files on a specific mount point).
-    # To re-enable an example, remove its pattern from this list.
-    "ignore_pattern": r"SWC-plusmaze_to_benchmark",
+    "reference_url": {"poseinterface": None},
+    "filename_pattern": "/*.py",  # which files to execute before inclusion
 }
 
 # -- linkcheck configuration -------------------------------------------------