docs: describe formats (#75)

Closes #74, cc @scottyhq

Author: gadomski

docs/.markdownlint-cli2.jsonc

@@ -0,0 +1,3 @@
+{
+  "config": { "reference-links-images": false }
+}

docs/api/index.md

@@ -5,3 +5,25 @@ description: The stacrs Python API
 # Python API
 
 API documentation for the **stacrs** Python package.
+
+## Format
+
+Several functions, including [stacrs.write][], take a `format` argument.
+Valid values are:
+
+- `json` or `geojson`: compact (no whitespace) JSON
+- `json-pretty` or `geojson-pretty`: indented JSON
+- `ndjson`: newline-delimited JSON (also known as `geojson-seq`)
+- `parquet` or `geoparquet`: uncompressed geoparquet
+- `parquet[{compression}]` or `geoparquet[{compression}]`: compressed parquet, where valid values for `compression` are the lowercase string versions of the values enumerated in [stac::geoparquet::Compression](https://docs.rs/stac/latest/stac/geoparquet/enum.Compression.html).
+
+!!! tip
+
+    If you're not sure which geoparquet compression to use, we suggest `parquet[snappy]`
+
+!!! note
+
+    The distinction between pretty and compact JSON, or compressed and uncompressed geoparquet, is only relevant on write.
+    On read, the formats are treated the same.
+
+Under the hood, the `format` argument is parsed into a [Format](https://docs.rs/stac/latest/stac/enum.Format.html) enum.

docs/api/walk.md

@@ -0,0 +1,3 @@
+# Walk
+
+::: stacrs.walk

docs/example.ipynb

@@ -26,6 +26,7 @@ nav:
       - read: api/read.md
       - search: api/search.md
       - version: api/version.md
+      - walk: api/walk.md
       - write: api/write.md
   - CONTRIBUTING.md
 
@@ -48,7 +49,7 @@ plugins:
             show_source: false
             show_symbol_type_toc: true
             signature_crossrefs: true
-          import:
+          inventories:
             - https://kylebarron.dev/arro3/latest/objects.inv
   - search
   - social:

mkdocs.yml

@@ -60,6 +60,7 @@ dev = [
 docs = [
     "contextily>=1.6.2",
     "humanize>=4.12.1",
+    "ipykernel>=6.29.5",
     "jinja2>=3.1.4",
     "mike>=2.1.3",
     "mkdocs-jupyter>=0.25.1",

pyproject.toml

@@ -12,3 +12,10 @@ async def test_write(item: dict[str, Any], tmp_path: Path) -> None:
     table = pyarrow.parquet.read_table(path)
     items = list(stac_geoparquet.arrow.stac_table_to_items(table))
     assert len(items) == 1
+
+
+async def test_write_compressed(item: dict[str, Any], tmp_path: Path) -> None:
+    path = str(tmp_path / "out.parquet")
+    await stacrs.write(path, [item], format="parquet[snappy]")
+    metadata = pyarrow.parquet.read_metadata(path)
+    assert metadata.row_group(0).column(0).compression == "SNAPPY"