Improve documentation for TestData

[m-mohr]

A couple of questions that came up when reading the TestData documentation at https://stactools.readthedocs.io/en/stable/api.html?highlight=test#module-stactools.testing.test_data

path (str) – The path to the file at the root of the test data directory.

What is the test data directory? Is this meant to be the file name after or before compression? Or is there no connection?

get_external_data(rel_path): Returns an absolute path to a local test file after downloading it from an external source.
get_path(rel_path): Returns an absolute path to a local test file.

rel_path parameter: Is this the path passed to TestData as first parameter or the key in the external_data dict (I assume the latter)? There are just so many different paths...

For get_external_data it should be made more clear that this is the function that actually downloads the data. The description sounds a bit more like it just returns a path in case something has been downloaded.

Is the returned path the path of the zip file (in case it is zipped) or the extracted file(s) or the path to a folder where it has been extracted to? Can a ZIP file contain multiple files?

Does this cache files? So if I run the tests twice does it download files once or twice?

external_data

This structure is not defined. What keys can it have? It seems like it is url, compress, s3 and planetary_computer?
What does compress mean? That the file is zipped and should be extracted? Or that the downloaded file should be zipped after download?

---

I could find some answers by reading the code, but that should not be required.