Unexpected behavior when globbing nested directory structure as `jupyterlite_contents`

[mfisher87]

Problem

Story: I want to expose a directory structure in my jupyterlite instance. This jupyterlite instance is a part of a documentation site, and I want the jupyterlite instance to help users learn about the software I'm documenting. I want the top level of the jupyterlite directory structure to contain notebooks introducing concepts in a specific order. And I want to separate the data those notebooks use into a data/ subdirectory. E.g.:

.
├── 01-summary.ipynb
├── 02-basic-api.ipynb
├── 03-advanced-api.ipynb
└── data
    ├── bar
    ├── baz
    │   ├── baz1
    │   └── baz2
    └── foo

When I set:

jupyterlite_contents = [
    "../examples/*",
]

My JupyterLite instance has a files directory structure like:

files/
├── 01-summary.ipynb
├── 02-basic-api.ipynb
├── 03-advanced-api.ipynb
├── bar
├── baz
|   ├── baz1
|   └── baz2
└── foo

(The contents of the "data" directory are flattened out to the root of files/)

When I set:

jupyterlite_contents = [
    "../examples/**",
]

I get in my JupyterLite deployment:

files/
├── 01-summary.ipynb
├── 02-basic-api.ipynb
├── 03-advanced-api.ipynb
├── bar
├── baz
|   ├── baz1
|   └── baz2
├── baz1
├── baz2
├── data
|   ├── bar
|   ├── baz
|   │   ├── baz1
|   │   └── baz2
|   └── foo
└── foo

(Every file and directory under data/ is recursively duplicated to their parent directory, so e.g. baz1 shows up 3 times)

I tried a few other permutations, and nothing gave the desired result of an exact recursive copy of the target directory.

My intuition is that ../examples/** is the correct way to recursively include all the files in ../examples, including nested directories.

Proposed Solution

Update docs to more clearly explain how the globs specified in jupyterlite_contents are passed to the jupyterlite build, and where users might be surprised.

Additional context

[mfisher87]

Well... one thing I didn't try was a directory without a glob expression:

jupyterlite_contents = [
    "../examples",
]

This does what I want! However, the behavior of duplicating files when using a glob is still surprising. I think the docs could be updated to more clearly specify how the results of the glob are passed to the jupyterlite build as separate --contents arguments.

If you agree with this approach, I'd be happy to work on the docs a bit.