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://github.com/uber/h3-py-notebooks
-    title: Example Notebooks
-  - url: https://h3geo.org/
-    title: H3 Project Homepage
-  - url: https://github.com/uber/h3-py
-    title: h3-py on GitHub
-  - url: https://github.com/uber/h3
-    title: H3 on GitHub
-  - url: https://github.com/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://github.com/uber/h3)
+- [H3 Project GitHub Discussions](https://github.com/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://github.com/uber/h3-py-notebooks)
+- [h3-py on GitHub](https://github.com/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://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/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://github.com/uber/h3-py/issues/new),
 [Discussions](https://github.com/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)
-Original file line number
+Diff line change
@@ Expand Up / @@ -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:
@@ Expand Down @@