From c09c43ef0ae652f0ea52647940dd7c5ea25da8cd Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 14 Apr 2024 09:36:07 -0700 Subject: [PATCH] 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/upload-artifact@v4.3.1 * 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/gh-action-pypi-publish@v1.8.14 * try pypa/cibuildwheel@v2.17.0 * Revert "try pypa/cibuildwheel@v2.17.0" This reverts commit fa8f7c9ab36ae093c66b087b9ba672d0fa67541c. * SDist doesn't need a strategy matrix * shorten names for cibw * bump actions/download-artifact@v4.1.4 --- .github/workflows/build_docs.yml | 47 ++++++++++++++++++++++++++++ .github/workflows/coverage-lint.yml | 6 ++-- .github/workflows/deploy_docs.yml | 48 ----------------------------- .github/workflows/wheels.yml | 44 ++++++++++++++++---------- CHANGELOG.md | 4 ++- docs/_toc.yml | 29 +++++------------ docs/api_comparison.md | 2 +- docs/api_reference.md | 4 +-- docs/polygon_tutorial.ipynb | 4 +-- docs/project_links.md | 19 ++++++++++++ makefile | 1 + readme.md | 6 ++-- 12 files changed, 117 insertions(+), 97 deletions(-) create mode 100644 .github/workflows/build_docs.yml delete mode 100644 .github/workflows/deploy_docs.yml create mode 100644 docs/project_links.md diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 00000000..f66ad469 --- /dev/null +++ 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/checkout@v4.1.1 + with: + submodules: recursive + + - uses: actions/setup-python@v5.0.0 + 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/upload-artifact@v4.3.1 + 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 index 7f3c1814..24ec82e1 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -40,10 +40,11 @@ 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: | @@ -51,6 +52,7 @@ jobs: 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 deleted file mode 100644 index ceec196a..00000000 --- a/.github/workflows/deploy_docs.yml +++ /dev/null @@ -1,48 +0,0 @@ -name: deploy_docs - -# todo: we want to build on PRs, but keep it from pushing to deploy... - -on: - push: - branches: - - master - -# This job installs dependencies, builds the book, and pushes it to `gh-pages` -jobs: - build-docs: - name: Build docs - runs-on: ubuntu-22.04 - - steps: - - uses: actions/checkout@v4.1.1 - with: - submodules: recursive - - - uses: actions/setup-python@v5.0.0 - with: - python-version: 3.11 - - - name: Install dependencies - run: | - pip install --upgrade pip setuptools wheel - pip install -r requirements.in - pip install .[all] - - - name: Lint - # run: flake8 --ignore=E501 h3.py - run: flake8 src/h3 - - # Build the book - - name: Build the book - # turn off warningiserror just for https://github.com/uber/h3-py/pull/283 - # jupyter-book build docs/ --warningiserror --keep-going --all - run: | - jupyter-book build docs/ --keep-going --all - - - # Deploy the book's HTML to gh-pages branch - - name: GitHub Pages action - uses: peaceiris/actions-gh-pages@v3.9.3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: docs/_build/html diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 393d3572..828699b6 100644 --- 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/checkout@v4.1.1 @@ -34,6 +29,8 @@ jobs: - name: Setup Python uses: actions/setup-python@v5.0.0 + 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 index 694ca058..1d38898e 100644 --- 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 index 9d53f89d..9ebe6187 100644 --- 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 index e3ce64ba..6abfc80b 100644 --- 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 index 526c85bd..e11e8b05 100644 --- 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 index fde0ce21..c5efd91e 100644 --- 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 new file mode 100644 index 00000000..d9f9d633 --- /dev/null +++ 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 index 56b97d96..22b80e5a 100644 --- 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 index eab09ad0..d4142be9 100644 --- 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'`.
+`pip install 'h3==4.0.0b3'`.
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)