generate_carousel_stubs.py

#!/usr/bin/env python3
"""Generate stub carousel files for the dataset gallery.

This script creates minimal placeholder files for the dataset gallery carousels
that are normally auto-generated by PyVista's documentation build process.
This is needed for translation builds where the full PyVista build is not run.
"""

import os
from pathlib import Path

# List of carousel files that are referenced in dataset_gallery.rst
CAROUSEL_FILES = [
    'all_datasets_carousel.rst',
    'builtin_carousel.rst',
    'downloads_carousel.rst',
    'planets_carousel.rst',
    'pointset_carousel.rst',
    'polydata_carousel.rst',
    'unstructuredgrid_carousel.rst',
    'structuredgrid_carousel.rst',
    'explicitstructuredgrid_carousel.rst',
    'pointcloud_carousel.rst',
    'surfacemesh_carousel.rst',
    'rectilineargrid_carousel.rst',
    'imagedata_carousel.rst',
    'imagedata_3d_carousel.rst',
    'imagedata_2d_carousel.rst',
    'texture_carousel.rst',
    'cubemap_carousel.rst',
    'multiblock_carousel.rst',
    'multiblock_homo_carousel.rst',
    'multiblock_hetero_carousel.rst',
    'multiblock_single_carousel.rst',
    'misc_carousel.rst',
    'medical_carousel.rst',
]

STUB_CONTENT = """.. note::

   This section is auto-generated during the full PyVista documentation build.
   For the complete dataset gallery with interactive examples, please visit
   the `PyVista documentation <https://docs.pyvista.org/>`_.

"""

def main():
    """Create stub carousel files if they don't exist."""
    # Get the directory where this script is located
    script_dir = Path(__file__).parent

    # When building from the root (translation builds), carousel files need to be at two locations:
    # 1. pyvista/doc/source/api/examples/dataset-gallery/ (for building pyvista docs directly)
    # 2. api/examples/dataset-gallery/ (for building from root with /api/... includes)

    carousel_dirs = [
        script_dir / 'pyvista' / 'doc' / 'source' / 'api' / 'examples' / 'dataset-gallery',
        script_dir / 'api' / 'examples' / 'dataset-gallery',
    ]

    for carousel_dir in carousel_dirs:
        # Create the directory if it doesn't exist
        carousel_dir.mkdir(parents=True, exist_ok=True)

        created_count = 0
        skipped_count = 0

        for filename in CAROUSEL_FILES:
            filepath = carousel_dir / filename

            if not filepath.exists():
                filepath.write_text(STUB_CONTENT)
                print(f"Created stub: {carousel_dir.relative_to(script_dir)}/{filename}")
                created_count += 1
            else:
                skipped_count += 1

        print(f"  Summary for {carousel_dir.relative_to(script_dir)}: Created {created_count}, skipped {skipped_count}\n")

        # Create a marker file to indicate these are stubs
        marker_file = carousel_dir / '.stub_files_generated'
        marker_file.write_text("These carousel files are stubs generated for translation builds.\n")

if __name__ == '__main__':
    main()