feat(docs): move docs to top-level

stac-utils · Sep 21, 2024 · d5fb7fa · d5fb7fa
1 parent a50bea1
commit d5fb7fa
Show file tree

Hide file tree

Showing 34 changed files with 311 additions and 89 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,65 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - python/**
+  pull_request:
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - python/**
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Install doc requirements
+        run: pip install -r requirements-docs.txt
+      - uses: PyO3/maturin-action@v1
+        with:
+            command: build
+            args: --manifest-path python/Cargo.toml --out dist
+      - name: Install stacrs
+        run: pip install stacrs --find-links dist --no-index
+      - name: Build docs
+        run: mkdocs build --strict
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'site'
+  deploy:
+    environment:
+      name: "github-pages"
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    if: success() && startsWith(github.ref, 'refs/heads/main')
+    needs:
+      - build
+    steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - uses: actions/download-artifact@v4
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml
@@ -28,7 +28,7 @@ jobs:
       - name: Install dev requirements
         run: pip install -r python/requirements-dev.txt
       - name: Build
-        run: maturin build --manifest-path python/Cargo.toml --out dist -F geoparquet
+        run: maturin build --manifest-path python/Cargo.toml --out dist
       - name: Install stacrs
         run: pip install stacrs --find-links dist --no-index
       - name: Check
@@ -63,7 +63,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml -F geoparquet
+          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml
           sccache: 'true'
       - name: Upload wheels
         uses: actions/upload-artifact@v4
@@ -123,7 +123,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml -F geoparquet
+          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml
           sccache: 'true'
       - name: Upload wheels
         uses: actions/upload-artifact@v4
@@ -151,7 +151,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml -F geoparquet
+          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml
           sccache: 'true'
       - name: Upload wheels
         uses: actions/upload-artifact@v4

diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,5 @@
 Cargo.lock
 dist/
 pyrightconfig.json
+site/
+.cache
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 ![Crates.io](https://img.shields.io/crates/l/stac?style=for-the-badge)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=for-the-badge)](./CODE_OF_CONDUCT)
 
-![Ferris the crab holding the STAC logo](./img/rustacean-and-stac-small.png)
+![Ferris the crab holding the STAC logo](./img/ferris-holding-stac-small.png)
 
 Command Line Interface (CLI), Rust crates, and other libraries for the [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/) specification.
 
@@ -39,7 +39,7 @@ Install with **pip**:
 pip install stacrs
 ```
 
-See [the documentation](https://stacrs.readthedocs.io/) for more information.
+See [the documentation](https://stac-utils.github.io/stac-rs/python/) for more information.
 
 ## Development
 

diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -0,0 +1,29 @@
+# Command-line interface (CLI)
+
+The **stac-rs** command-line interface can be installed two ways.
+If you have Rust, use `cargo`:
+
+```shell
+cargo install stac-cli
+```
+
+If you have Python, use `pip`:
+
+```shell
+pip install stacrs-cli
+```
+
+!!! Note
+    <!-- markdownlint-disable-next-line MD046 -->
+    The PyPI version of the CLI does not contain bindings to GDAL. This
+    shouldn't be a problem for most users, but if you're using `stacrs item
+    image.tiff` to generate new STAC items from a raster, you'll need to install
+    from `cargo`.
+
+The CLI is called **stacrs**:
+
+```shell
+stacrs --help
+```
+
+For examples of using the CLI, check out the slides from [@gadomski's](https://github.com/gadomski/) 2024 FOSS4G-NA presentation [here](https://www.gadom.ski/2024-09-FOSS4G-NA-stac-rs/).
diff --git a/docs/img/rustacean-and-stac-small.png b/docs/img/rustacean-and-stac-small.png
@@ -0,0 +1 @@
+../../img/rustacean-and-stac-small.png
diff --git a/docs/img/stac-ferris-favicon.png b/docs/img/stac-ferris-favicon.png
@@ -0,0 +1 @@
+../../img/stac-ferris-favicon.png
diff --git a/docs/img/stac-ferris.png b/docs/img/stac-ferris.png
@@ -0,0 +1 @@
+../../img/stac-ferris.png
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,17 @@
+# stac-rs
+
+![Ferris holding STAC](./img/ferris-holding-stac-small.png)
+
+Command Line Interface (CLI), Rust crates, and other libraries for the [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/) specification.
+
+## Python documentation
+
+Our Python package is named **stacrs** and its documentation is available [here](./python/index.md).
+
+## Rust documentation on docs.rs
+
+- [stac](https://docs.rs/stac): The core Rust crate
+- [stac-api](https://docs.rs/stac-api): Data structures for a STAC API, and a client for searching one
+- [stac-validate](https://docs.rs/stac-validate): Efficiently validate STAC objects with [json-schema](https://json-schema.org/)
+- [stac-server](https://docs.rs/stac-server): A STAC API server with multiple backends
+- [pgstac](https://docs.rs/pgstac): Rust bindings for [pgstac](https://github.com/stac-utils/pgstac)
diff --git a/python/docs/api/index.md → docs/python/api/index.md b/python/docs/api/index.md → docs/python/api/index.md
@@ -1,6 +1,6 @@
-# API
+# Python API
 
-API documentation for **stacrs**.
+API documentation for the **stacrs** Python package.
 
 - [migrate](./migrate.md)
 - [search](./search.md)

diff --git a/python/docs/api/migrate.md → docs/python/api/migrate.md b/python/docs/api/migrate.md → docs/python/api/migrate.md
diff --git a/python/docs/api/pystac.md → docs/python/api/pystac.md b/python/docs/api/pystac.md → docs/python/api/pystac.md
diff --git a/python/docs/api/read.md → docs/python/api/read.md b/python/docs/api/read.md → docs/python/api/read.md
diff --git a/python/docs/api/search.md → docs/python/api/search.md b/python/docs/api/search.md → docs/python/api/search.md
diff --git a/python/docs/api/validate.md → docs/python/api/validate.md b/python/docs/api/validate.md → docs/python/api/validate.md
diff --git a/python/docs/api/write.md → docs/python/api/write.md b/python/docs/api/write.md → docs/python/api/write.md
diff --git a/docs/python/index.md b/docs/python/index.md
@@ -0,0 +1,71 @@
+# stacrs
+
+A Python package for working with [STAC](https://stacspec.org) designed to compliment existing packages such as [pystac](https://pystac.readthedocs.io) and [pystac-client](https://pystac-client.readthedocs.io).
+
+## Usage
+
+Install via **pip**:
+
+```shell
+pip install stacrs
+```
+
+Then:
+
+```python
+import stacrs
+
+# Search a STAC API
+items = stacrs.search(
+    "https://landsatlook.usgs.gov/stac-server",
+    collections="landsat-c2l2-sr",
+    intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
+    sortby="-properties.datetime",
+    max_items=100,
+)
+
+# Write items to a stac-geoparquet file
+stacrs.write("items.parquet", items)
+
+# Read items from a stac-geoparquet file as an item collection
+item_collection = stacrs.read("items.parquet")
+
+# Use `search_to` for better performance if you know you'll be writing the items
+# to a file
+stacrs.search_to(
+    "items.parquet",
+    "https://landsatlook.usgs.gov/stac-server",
+    collections="landsat-c2l2-sr",
+    intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
+    sortby="-properties.datetime",
+    max_items=100,
+)
+```
+
+### pystac
+
+If [pystac](https://pystac.readthedocs.io) is present, `stacrs.pystac` provides functions that take **pystac** objects as their inputs and outputs:
+
+```python
+import pystac
+import stacrs.pystac
+
+item = pystac.read_file("item.json")
+stacrs.pystac.validate(item)
+
+items = list(stacrs.pystac.search(...))
+```
+
+You can install **pystac** with **stacrs** via an optional dependency:
+
+```shell
+pip install 'stacrs[pystac]'
+```
+
+## Comparisons
+
+This package (intentionally) has limited functionality, as it is _not_ intended to be a replacement for existing Python STAC packages.
+[pystac](https://pystac.readthedocs.io) is a mature Python library with a significantly richer API for working with STAC objects.
+For querying STAC APIs, [pystac-client](https://pystac-client.readthedocs.io) is more feature-rich than our simplistic `stacrs.search`.
+
+That being said, it is hoped that **stacrs** will be a nice complement to the existing Python STAC ecosystem by providing a no-dependency package with unique capabilities, such as searching directly into a stac-geoparquet file.
diff --git a/img/rustacean-and-stac-small.png → img/ferris-holding-stac-small.png b/img/rustacean-and-stac-small.png → img/ferris-holding-stac-small.png
diff --git a/img/rustacean-and-stac.png → img/ferris-holding-stac.png b/img/rustacean-and-stac.png → img/ferris-holding-stac.png
diff --git a/img/rustacean-and-stac.xcf → img/ferris-holding-stac.xcf b/img/rustacean-and-stac.xcf → img/ferris-holding-stac.xcf
diff --git a/img/stac-ferris-favicon.png b/img/stac-ferris-favicon.png
diff --git a/img/stac-ferris.png b/img/stac-ferris.png
diff --git a/img/stac-ferris.xcf b/img/stac-ferris.xcf
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,64 @@
+site_name: stac-rs
+site_url: https://stac-utils.github.io/stac-rs
+repo_url: https://github.com/stac-utils/stac-rs
+theme:
+  name: material
+  logo: img/stac-ferris.png
+  icon:
+    repo: fontawesome/brands/github
+  favicon: img/stac-ferris-favicon.png
+  features:
+    - navigation.indexes
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+nav:
+  - Home: index.md
+  - Python:
+      - python/index.md
+      - API:
+          - python/api/index.md
+          - migrate: python/api/migrate.md
+          - read: python/api/read.md
+          - search: python/api/search.md
+          - validate: python/api/validate.md
+          - write: python/api/write.md
+          - pystac: python/api/pystac.md
+  - Command-line interface:
+      - cli/index.md
+plugins:
+  - search
+  - social
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          load_external_modules: false
+          options:
+            show_root_heading: true
+            show_signature: true
+            show_signature_annotations: true
+            separate_signature: true
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.details
diff --git a/python/.gitignore b/python/.gitignore
@@ -70,5 +70,3 @@ docs/_build/
 
 # Pyenv
 .python-version
-
-site
diff --git a/python/.readthedocs.yaml b/python/.readthedocs.yaml
diff --git a/python/Cargo.toml b/python/Cargo.toml
@@ -12,18 +12,17 @@ publish = false
 name = "stacrs"
 crate-type = ["cdylib"]
 
-[features]
-geoparquet = [
-    "stac/geoparquet-compression",
-] # need to be able to disable geoparquet so this builds on readthedocs
-
 [dependencies]
 geojson = "0.24"
 pyo3 = { version = "0.22", features = ["extension-module"] }
 pythonize = "0.22"
 serde = "1"
 serde_json = "1"
-stac = { path = "../core", features = ["reqwest", "object-store-all"] }
+stac = { path = "../core", features = [
+    "geoparquet-compression",
+    "object-store-all",
+    "reqwest",
+] }
 stac-api = { path = "../api", features = ["client"] }
 stac-validate = { path = "../validate", features = ["blocking"] }
 tokio = { version = "1", features = ["rt"] }
diff --git a/python/README.md b/python/README.md
@@ -2,7 +2,6 @@
 
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/stac-utils/stac-rs/ci.yml?branch=main&style=for-the-badge)](https://github.com/stac-utils/stac-rs/actions/workflows/ci.yml)
 [![PyPI - Version](https://img.shields.io/pypi/v/stacrs?style=for-the-badge)](https://pypi.org/project/stacrs)
-[![Read the Docs](https://img.shields.io/readthedocs/stacrs?style=for-the-badge)](https://stacrs.readthedocs.io/)
 ![PyPI - License](https://img.shields.io/pypi/l/stacrs?style=for-the-badge)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=for-the-badge)](./CODE_OF_CONDUCT)
 
@@ -48,6 +47,8 @@ stacrs.search_to(
 )
 ```
 
+See [the API documentation](https://stac-utils.github.io/stac-rs/python/api/) for details.
+
 ### pystac
 
 If [pystac](https://pystac.readthedocs.io) is present, `stacrs.pystac` provides functions that take **pystac** objects as their inputs and outputs:

diff --git a/python/docs/CODE_OF_CONDUCT b/python/docs/CODE_OF_CONDUCT
diff --git a/python/docs/index.md b/python/docs/index.md