Update docs to include polygon tutorial

.github/workflows/build_docs.yml

@@ -0,0 +1,47 @@
+name: build_docs
+
+on:
+ push:
+ branches: [master]
+ pull_request:
+ branches: ['*']
+
+jobs:
+ build-docs:
+ runs-on: ubuntu-22.04
+
+ steps:
+ - uses: actions/[email protected]
+ with:
+ submodules: recursive
+
+ - uses: actions/[email protected]
+ with:
+ python-version: 3.11
+
+ - name: Install dependencies
+ run: |
+ pip install --upgrade pip setuptools wheel
+ pip install -r requirements.in
+ pip install -r requirements-dev.txt
+ pip install .[all]
+
+ - name: Build the book
+ run: jupyter-book build docs/ --warningiserror --keep-going --all
+
+ - name: Upload artifacts to GitHub
+ uses: actions/[email protected]
+ with:
+ name: html
+ path: docs/_build/html
+
+ deploy-docs:
+ needs: [build-docs]
+ runs-on: ubuntu-22.04
+ if: github.event.pull_request.merged
+
+ steps:
+ - uses: peaceiris/actions-gh-pages@v4
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: docs/_build/html

.github/workflows/coverage-lint.yml

@@ -40,17 +40,19 @@ jobs:
  pytest --cov=h3 --full-trace --cov-report=xml
 
  - name: Upload coverage to Codecov
- uses: codecov/codecov-action@v3.0.0
+ uses: codecov/codecov-action@v4.3.0
  with:
  file: ./coverage.xml
  fail_ci_if_error: true
+ token: ${{ secrets.CODECOV_TOKEN }}
 
  - name: Copy Cython annotations to project dir
  run: |
  mkdir annotations
  cp _skbuild/*/cmake-build/src/h3/_cy/*.html ./annotations
 
  - name: Upload artifacts to GitHub
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4.3.1
  with:
+ name: annotations
  path: ./annotations

.github/workflows/wheels.yml

@@ -19,13 +19,8 @@ on:
 
 jobs:
  make_sdist:
- name: 'SDist: ${{ matrix.os }}'
  if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
- runs-on: ${{ matrix.os }}
-
- strategy:
- matrix:
- os: [ubuntu-22.04]
+ runs-on: ubuntu-22.04
 
  steps:
  - uses: actions/[email protected]
@@ -34,6 +29,8 @@ jobs:
 
  - name: Setup Python
  uses: actions/[email protected]
+ with:
+ python-version: 3.11
 
  - name: Make sdist
  run: |
@@ -52,12 +49,13 @@ jobs:
  run: pytest --cov=h3 --full-trace
 
  - name: Upload artifacts to GitHub
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4.3.1
  with:
+ name: temp_result_sdist
  path: ./dist
 
- make_cibw_v2_wheels:
- name: 'cibuildwheel v2: ${{ matrix.name }}'
+ make_wheels:
+ name: 'cibuildwheel: ${{ matrix.name }}'
  if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
  runs-on: ${{ matrix.os }}
  strategy:
@@ -133,21 +131,35 @@ jobs:
  pipx run twine check wheelhouse/*
 
  - name: Upload artifacts to GitHub
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4.3.1
  with:
+ name: temp_result_${{ matrix.os }}-${{ strategy.job-index }}
  path: wheelhouse/*.whl
 
- upload_all:
- needs: [make_sdist, make_cibw_v2_wheels]
- runs-on: ubuntu-22.04
+ merge:
+ needs: [make_sdist, make_wheels]
+ runs-on: ubuntu-latest
+ steps:
+ - name: Merge Artifacts
+ uses: actions/upload-artifact/merge@v4
+ with:
+ name: wheels_and_sdist
+ pattern: temp_result_*
+ delete-merged: true
+ retention-days: 7
+ compression-level: 9
+
+ to_pypi:
+ needs: [merge]
  if: github.event_name == 'release' && github.event.action == 'published'
+ runs-on: ubuntu-latest
 
  steps:
- - uses: actions/download-artifact@v3
+ - uses: actions/download-artifact@v4.1.4
  with:
- name: artifact
+ name: wheels_and_sdist
  path: dist
 
- - uses: pypa/gh-action-pypi-publish@v1.5.1
+ - uses: pypa/gh-action-pypi-publish@v1.8.14
  with:
  password: ${{ secrets.pypi_password }}

CHANGELOG.md

@@ -1,4 +1,6 @@
-# Versioning
+# CHANGELOG
+
+## Versioning
 
 The H3 core library adheres to [Semantic Versioning](http://semver.org/).
 H3-Py has a `major.minor.patch` version scheme. The major and minor version

docs/_toc.yml

@@ -4,31 +4,16 @@ format: jb-book
 
 root: intro
 parts:
-- caption: Getting started
+- caption: h3-py
  chapters:
  - file: api_comparison
  - file: api_reference
+ - file: polygon_tutorial
 
-- caption: Contributing
+- caption: Sundries
  chapters:
- - file: contributing
- # - file: jupyter_book_notes
  - file: _changelog
- title: Change log
-
-- caption: External links
- chapters:
- - url: https:/uber/h3-py-notebooks
- title: Example Notebooks
- - url: https://h3geo.org/
- title: H3 Project Homepage
- - url: https:/uber/h3-py
- title: h3-py on GitHub
- - url: https:/uber/h3
- title: H3 on GitHub
- - url: https:/uber/h3/discussions
- title: GitHub Discussions
- - url: https://stackoverflow.com/questions/tagged/h3
- title: H3 Stack Overflow
- - url: https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg
- title: H3 Slack
+ title: CHANGELOG
+ - file: contributing
+ - file: project_links
+ title: Project Links

docs/api_comparison.md

@@ -1,4 +1,4 @@
-# API comparison
+# API Comparison
 
 The `h3-py` library provides several APIs which share the same functions,
 but differ in their input and output types:

docs/api_reference.md

@@ -1,4 +1,4 @@
-# API reference
+# API Reference
 
 This page lists the functions that are common to each of the
 [provided APIs](api_comparison).
@@ -59,8 +59,6 @@ Functions relating H3 objects to geographic (lat/lng) coordinates.
  average_hexagon_edge_length
  cell_to_boundary
  directed_edge_to_boundary
- polygon_to_cells
- cells_to_polygons
 ```
 
 ### Hierarchical relationships

docs/polygon_tutorial.ipynb

@@ -5,7 +5,7 @@
  "id": "03ee1f11-7a60-4761-aaf7-673ea04e7dca",
  "metadata": {},
  "source": [
- "# H3 and (Multi)Polygons\n",
+ "# Polygon Tutorial\n",
  "\n",
  "`h3-py` can convert between sets of cells and GeoJSON-like polygon and multipolygon shapes.\n",
  "\n",
@@ -928,7 +928,7 @@
  "name": "python",
  "nbconvert_exporter": "python",
  "pygments_lexer": "ipython3",
- "version": "3.11.1"
+ "version": "3.11.2"
  }
  },
  "nbformat": 4,

docs/project_links.md

@@ -0,0 +1,19 @@
+# Project Links
+
+## H3
+
+Links for the overall H3 project including the core C library and all language bindings (including
+Python!).
+
+- [H3 Project Homepage](https://h3geo.org/)
+- [H3 on GitHub](https:/uber/h3)
+- [H3 Project GitHub Discussions](https:/uber/h3/discussions)
+- [H3 on Stack Overflow](https://stackoverflow.com/questions/tagged/h3)
+- [H3 on Slack](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg)
+
+## h3-py
+
+Links specific to the H3 Python bindings.
+
+- [Example Notebooks](https:/uber/h3-py-notebooks)
+- [h3-py on GitHub](https:/uber/h3-py)

makefile

@@ -4,6 +4,7 @@ PYTHON=$(shell command -v python || command -v python3)
 
 
 build-docs:
+ ./env/bin/pip install -r requirements-dev.txt
  ./env/bin/jupyter-book build docs/ --warningiserror --keep-going --all
 
 open:

readme.md

@@ -13,11 +13,12 @@
 [![Tests](https:/uber/h3-py/workflows/tests/badge.svg)](https:/uber/h3-py/actions)
 [![codecov](https://codecov.io/gh/uber/h3-py/branch/master/graph/badge.svg)](https://codecov.io/gh/uber/h3-py)
 
+
 ----
-### ANNOUNCEMENT: v4.0.0 beta released!
+## ANNOUNCEMENT: v4.0.0 beta released!
 Install the latest beta version with `pip install h3 --pre`
 or with
-`pip install 'h3==4.0.0b2'`. <br>
+`pip install 'h3==4.0.0b3'`. <br>
 Feedback is welcome via
 [Issues](https:/uber/h3-py/issues/new),
 [Discussions](https:/uber/h3/discussions),
@@ -26,6 +27,7 @@ and
 
 ----
 
+
 Python bindings for the [H3 core library](https://h3geo.org/).
 
 - Documentation: [uber.github.io/h3-py](https://uber.github.io/h3-py)