docs: add gh pages support (ci); update documentation for quarto;

.github/workflows/ci.yaml

@@ -3,16 +3,16 @@ name: CI
 on:
   push:
     paths:
-      - 'src/**'
-      - 'tests/**'
-      - 'pyproject.toml'
-      - 'uv.lock'
-      - 'Cargo.toml'
-      - 'Cargo.lock'
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "Cargo.toml"
+      - "Cargo.lock"
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -34,9 +34,8 @@ jobs:
 
       - name: Install the project
         run: uv sync --all-extras --dev
-      
+
       # TODO(justin): test coverage
       # TODO(justin): ruff linting
       - name: Run tests
         run: uv run pytest
-

.github/workflows/documentation.yaml

@@ -0,0 +1,65 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  docs:
+    runs-on: ubuntu-24.04
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Set up Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          pyproject-file: "pyproject.toml"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install the project
+        run: uv sync --all-extras --group docs
+
+      - name: Build documentation
+        run: |
+          uv run quartodoc build --config docs/_quarto.yml --verbose
+          quarto render docs
+
+      - name: Upload documentation artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "docs/_build"
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,5 +1,7 @@
 # Custom
 
+/.quarto/
+
 # VS Code files
 .vscode
 

docs/.gitignore

@@ -0,0 +1,8 @@
+/.quarto/
+/_build/
+/objects.json
+/_sidebar.yml
+/reference
+/latest
+/stable
+/_environment

docs/_quarto.yml

@@ -0,0 +1,66 @@
+project:
+  type: website
+  output-dir: _build
+
+website:
+  title: "BEAR"
+  description: "An integrated building entity dataset"
+  repo-url: https://github.com/owp-spatial/bear
+  repo-actions: [issue]
+  repo-subdir: docs
+  page-navigation: true
+  navbar:
+    background: "#003087"
+    foreground: "#ffffff"
+    search: true
+    left:
+      - text: "Reference"
+        href: reference/
+    tools:
+      - icon: github
+        href: https://github.com/owp-spatial/bear
+        aria-label: BEAR GitHub Repository
+        target: _blank
+
+  sidebar:
+    - id: reference
+      contents: "_sidebar.yml"
+
+quartodoc:
+  style: pkgdown
+  title: "Built Environment Asset Registry"
+  package: bear
+  sidebar: _sidebar.yml
+  renderer:
+    style: markdown
+    show_signature_annotations: true
+
+  sections:
+    - title: Providers
+      desc: ""
+      contents:
+        - package: bear.typing
+          name: Provider
+        - package: bear.providers.registry
+          name: ProviderRegistry
+        - package: bear.providers.provider_microsoft
+          name: MicrosoftProvider
+        - package: bear.providers.provider_nad
+          name: NADProvider
+        - package: bear.providers.provider_openaddresses
+          name: OpenAddressesProvider
+        - package: bear.providers.provider_openstreetmap
+          name: OpenStreetMapProvider
+        - package: bear.providers.provider_usa_structures
+          name: USAStructuresProvider
+
+metadata-files:
+  - _sidebar.yml
+
+parser: numpy
+
+format:
+  html:
+    theme: cosmo
+    toc: true
+    smooth-scroll: true

docs/index.qmd

@@ -0,0 +1,6 @@
+---
+title: Built Environment Asset Registry
+---
+
+**BEAR** is an integrated contintental-scale geospatial dataset for building entities.
+This repository contains software for generating BEAR from known sources.

pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
     "geopandas>=1.0.1",
     "polars>=1.20.0",
     "pyarrow>=19.0.0",
-    "shapely>=2.1.0.dev0",
+    "shapely>=2.0.6",
 ]
 
 [project.urls]
@@ -35,6 +35,9 @@ dev = [
     "pytest>=8.3.4",
     "ruff>=0.9.2",
 ]
+docs = [
+    "quartodoc>=0.9.1",
+]
 
 [tool.pytest.ini_options]
 addopts = ["--import-mode=importlib"]
@@ -47,6 +50,3 @@ indent-width = 4
 
 [tool.ruff.format]
 quote-style = "double"
-
-[tool.uv.sources]
-shapely = { git = "https://github.com/shapely/shapely" }

src/bear/__init__.py

@@ -1,4 +0,0 @@
-from bear._core import hello_from_bin
-
-def main() -> None:
-    print(hello_from_bin())

src/bear/providers/provider_microsoft.py

@@ -11,10 +11,10 @@
 
 @register_provider("microsoft")
 class MicrosoftProvider(Provider):
-    """`Microsoft Building Footprints <https://github.com/microsoft/GlobalMLBuildingFootprints>`_ Provider
+    """[Microsoft Building Footprints](https://github.com/microsoft/GlobalMLBuildingFootprints) Provider
 
-    This data is licensed by Microsoft under the `Open Data Commons
-    Open Database License (ODbL) <https://opendatacommons.org/licenses/odbl/>`_.
+    This data is licensed by Microsoft under the [Open Data Commons
+    Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/>).
     """
 
     @classmethod

src/bear/providers/provider_nad.py

@@ -11,11 +11,11 @@
 
 @register_provider("nad")
 class NADProvider(Provider):
-    """`National Address Database (NAD) <https://www.transportation.gov/gis/national-address-database>`_ Provider
+    """[National Address Database (NAD)](https://www.transportation.gov/gis/national-address-database) Provider
 
     This data is a work of the federal government and is not subject to copyright protection
     in accordance with 17 U.S.C. § 105. It is available for re-use without limitation or restriction.
-    See the `NAD disclaimer <https://www.transportation.gov/mission/open/gis/national-address-database/national-address-database-nad-disclaimer>`_
+    See the [NAD disclaimer](https://www.transportation.gov/mission/open/gis/national-address-database/national-address-database-nad-disclaimer)
     for more details.
     """
 

src/bear/providers/provider_openaddresses.py

@@ -11,7 +11,7 @@
 
 @register_provider("openaddresses")
 class OpenAddressesProvider(Provider):
-    """`OpenAddresses <https://openaddresses.io/>`_ Provider
+    """[OpenAddresses](https://openaddresses.io/) Provider
 
     The datasets provided by OpenAddresses are individually licensed.
     Most are available under open licenses, but there is no guarantee.

src/bear/providers/provider_openstreetmap.py

@@ -11,10 +11,10 @@
 
 @register_provider("openstreetmap")
 class OpenStreetMapProvider(Provider):
-    """`OpenStreetMap <https://www.openstreetmap.org>`_ Provider
+    """[OpenStreetMap](https://www.openstreetmap.org) Provider
 
-    This data is licensed by the OpenStreetMap Foundation under the `Open Data Commons
-    Open Database License (ODbL) <https://opendatacommons.org/licenses/odbl/>`_.
+    This data is licensed by the OpenStreetMap Foundation under the [Open Data Commons
+    Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/).
     """
 
     @classmethod

src/bear/providers/provider_usa_structures.py

@@ -11,7 +11,7 @@
 
 @register_provider("usa_structures")
 class USAStructuresProvider(Provider):
-    """`USA Structures <https://gis-fema.hub.arcgis.com/pages/usa-structures>`_ Provider
+    """[USA Structures](https://gis-fema.hub.arcgis.com/pages/usa-structures) Provider
 
     The data is licensed under the Creative Commons By Attribution (CC BY 4.0) license.
     """

src/bear/providers/registry.py

@@ -20,14 +20,18 @@ class ProviderRegistry(metaclass=ProviderRegistryMeta):
     registered provider classes. The goal is to encapsulate provider
     modules so that access to those modules is done via this registry.
 
-    A module may register itself by calling::
+    A module may register itself by calling:
 
-        ProviderRegistry.register('mymodule', my_provider_obj)
+    ```python
+    ProviderRegistry.register('mymodule', my_provider_obj)
+    ```
 
-    Then, it can be accessed by calling::
+    Then, it can be accessed by calling:
 
-        ProviderRegistry.get('mymodule')
-        #> <my_provider_obj>
+    ```python
+    ProviderRegistry.get('mymodule')
+    #> <my_provider_obj>
+    ```
 
     The ProviderRegistry class cannot be instantiated.
     """
@@ -122,17 +126,21 @@ def register_provider(name: str, /, **kwargs) -> Callable[[Provider], Provider]:
 
     Example
     -------
-    Using the decorator::
+    Using the decorator:
 
-        @register_provider("my_provider")
-        class MyProvider(Provider):
-            ...
+    ```python
+    @register_provider("my_provider")
+    class MyProvider(Provider):
+        ...
+    ```
 
-    Is equivalent to::
+    Is equivalent to:
 
-        class MyProvider(Provider):
-            ...
-        ProviderRegistry.register("my_provider", MyProvider)
+    ```python
+    class MyProvider(Provider):
+        ...
+    ProviderRegistry.register("my_provider", MyProvider)
+    ```
     """
 
     def register_provider_decorator(cls: Provider):