Update docs to include polygon tutorial (#355)

* docs building correctly again * drop beta announcement * cleaning up docs a bit * i think this is where it was at... * bump beta in readme announcement * update action * pssssst. it's a secret * separate upload docs step * setps taken * want --warningiserror * need requirements for notebook * no need to run linter here * does this default thing work? * alas, chatgpt led me astray * gimme an artifact to check * bump to actions/[email protected] * slightly better names * artifacts need names now * set python version for sdist * try this one * all unique names * try cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }} * try merge action * try combining sdist and wheels into single result * upload should work * bump to pypa/[email protected] * try pypa/[email protected] * Revert "try pypa/[email protected]" This reverts commit fa8f7c9. * SDist doesn't need a strategy matrix * shorten names for cibw * bump actions/[email protected]
uber · Apr 14, 2024 · c09c43e · c09c43e
1 parent 89c3720
commit c09c43e
Show file tree

Hide file tree

Showing 12 changed files with 117 additions and 97 deletions.
diff --git a/.github/workflows/build_docs.yml b/.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
diff --git a/.github/workflows/coverage-lint.yml b/.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
diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml
diff --git a/.github/workflows/wheels.yml b/.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 }}
diff --git a/CHANGELOG.md b/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

diff --git a/docs/_toc.yml b/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
diff --git a/docs/api_comparison.md b/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:

diff --git a/docs/api_reference.md b/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

diff --git a/docs/polygon_tutorial.ipynb b/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,

diff --git a/docs/project_links.md b/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)
diff --git a/makefile b/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:

diff --git a/readme.md b/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)