diff --git a/.github/workflows/lint.yaml b/.github/workflows/ci-additional.yml similarity index 69% rename from .github/workflows/lint.yaml rename to .github/workflows/ci-additional.yml index 86f67b4..efa6aef 100644 --- a/.github/workflows/lint.yaml +++ b/.github/workflows/ci-additional.yml @@ -4,11 +4,21 @@ on: pull_request: branches: [main] -name: Lint +name: CI Additional jobs: - lint: - name: mypy + check-links: + name: Check markdown hyperlinks + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v4 + + - name: Markdown link check + uses: gaurav-nelson/github-action-markdown-link-check@v1 + + mypy: + name: Mypy runs-on: ubuntu-latest defaults: run: @@ -16,7 +26,7 @@ jobs: steps: - name: Checkout repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Setup micromamba uses: mamba-org/setup-micromamba@v1 diff --git a/.github/workflows/run-tests.yaml b/.github/workflows/run-tests.yaml index f60e935..5b380a5 100644 --- a/.github/workflows/run-tests.yaml +++ b/.github/workflows/run-tests.yaml @@ -37,7 +37,7 @@ jobs: steps: - name: Checkout repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Get Date id: get-date @@ -55,7 +55,7 @@ jobs: python=${{ matrix.python-version }} - name: Fetch s2geography - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: repository: paleolimbot/s2geography ref: main @@ -100,7 +100,7 @@ jobs: pytest . -vv - name: Generate and upload coverage report - uses: codecov/codecov-action@v3 + uses: codecov/codecov-action@v5 with: gcov: true gcov_include: src diff --git a/README.md b/README.md index 7ba6665..132c0a0 100644 --- a/README.md +++ b/README.md @@ -13,78 +13,41 @@ the widely deployed open-source geometry library [s2geography](https://github.com/paleolimbot/s2geography) which provides a [GEOS](https://libgeos.org) compatibility layer on top of s2geometry. -This library is at an early stage of development. - -## Requirements - -- Python -- Numpy -- [s2geography](https://github.com/paleolimbot/s2geography) v0.2.0 or higher -- [s2geometry](https://github.com/google/s2geometry) v0.11.1 or higher - -Additional requirements when building spherely from source: - -- C++ compiler supporting C++17 standard -- CMake -- [scikit-build-core](https://github.com/scikit-build/scikit-build-core) - -(Note: C++11 or C++14 should work too but we have no plan to maintain -compatibility with those older standards) +**This library is at an early stage of development.** ## Installation -There is no pre-compiled package available at the moment. See the section below -for instructions on how to setup a development environment and build / install -spherely from source. +The easiest way to install Spherely is via its binary packages available for +Linux, MacOS, and Windows platforms on [conda-forge](https://conda-forge.org/) +and [PyPI](https://pypi.org/project/spherely/). -## Setting up a development environment using conda +Install the binary wheel using [pip](https://pip.pypa.io/): -After cloning this repo, create a conda environment using the `ci/environment.yml` -file with the required dependencies: - -``` -$ conda env create -f spherely/ci/environment.yml -$ conda activate spherely-dev +``` sh +$ pip install spherely ``` -Build and install `s2spherely`: +Install the conda-forge package using +[conda](https://docs.conda.io/projects/conda/en/stable/): -``` -$ cd spherely -$ python -m pip install . -v --no-build-isolation +``` sh +$ conda install spherely --channel conda-forge ``` -Note that you can specify a build directory in order to avoid rebuilding the -whole library from scratch each time after editing the code (requires -scikit-build-core v0.2.0+): +To compile and install Spherely from source, see detailed instructions in the +[documentation](https://spherely.readthedocs.io/en/latest/install.html). -``` -$ python -m pip install . -v --no-build-isolation --config-settings build-dir=build/skbuild -``` - -Run the tests: - -``` -$ pytest . -v -``` - -Spherely also uses [pre-commit](https://pre-commit.com/) for code -auto-formatting and linting at every commit. After installing it, you can enable -pre-commit hooks with the following command: +## Documentation -``` -$ pre-commit install -``` +https://spherely.readthedocs.io -(Note: you can skip the pre-commit checks with `git commit --no-verify`) +## License -## Using the latest s2geography version +Spherely is licensed under BSD 3-Clause license. See the LICENSE file for more +details. -If you want to compile spherely against the latest version of s2geography, use: +## Acknowledgment - ``` - $ git clone https://github.com/paleolimbot/s2geography - $ cmake -S s2geography -B s2geography/build -DCMAKE_CXX_STANDARD=17 -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX - $ cmake --build s2geography/build - $ cmake --install s2geography/build - ``` +The development of this project has been supported by two +[NumFOCUS](https://numfocus.org) Small Development Grants (GeoPandas 2022 round +1 and GeoPandas 2023 round 3). diff --git a/docs/conf.py b/docs/conf.py index f75c6c6..d7b99bd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,8 +1,14 @@ # -*- coding: utf-8 -*- +import spherely + project = "spherely" +author = "Spherely developers" copyright = "2022, Spherely Developers" -author = "Benoit Bovy" +# The short X.Y version. +version = spherely.__version__.split("+")[0] +# The full version, including alpha/beta/rc tags. +release = spherely.__version__ # -- General configuration ---------------------------------------------- @@ -32,11 +38,12 @@ "array-like": ":term:`array-like `", } -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" +source_suffix = [".rst", ".md"] master_doc = "index" +language = "en" + exclude_patterns = [ "**.ipynb_checkpoints", "build/**.ipynb", @@ -56,13 +63,11 @@ html_theme_options = dict( repository_url="https://github.com/benbovy/spherely", repository_branch="main", - path_to_docs="doc", + path_to_docs="docs", use_edit_page_button=True, use_repository_button=True, use_issues_button=True, home_page_in_toc=False, - extra_navbar="", - navbar_footer_text="", ) html_static_path = ["_static"] diff --git a/docs/environment.yml b/docs/environment.yml index 476a1d7..7f2d47d 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -3,7 +3,7 @@ name: spherely-docs channels: - conda-forge dependencies: - - python=3.10 + - python=3.11 - numpy - cxx-compiler - cmake @@ -12,8 +12,8 @@ dependencies: - s2geography>=0.2.0 - libabseil - sphinx - - pydata-sphinx-theme>=0.8.1 - - sphinx-book-theme>=0.3.3 + - pydata-sphinx-theme=0.15.4 + - sphinx-book-theme=1.1.3 - myst-nb - pip # TODO: install the library here when s2geography is packaged diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..4303566 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,38 @@ +# Spherely Documentation + +Manipulation and analysis of geometric objects on the sphere. + +Spherely is the counterpart of [Shapely] (2.0+) for manipulation and analysis +of spherical geometric objects. It is using the widely deployed open-source +geometry library [s2geometry] via the library [s2geography] which provides a +[GEOS] compatibility layer on top of s2geometry. + +**This library is at an early stage of development.** + +**Useful links**: +[Home](http://spherely.readthedocs.io/) | +[Code Repository](https://github.com/benbovy/spherely) | +[Issues](https://github.com/benbovy/spherely/issues) | +[Discussions](https://github.com/benbovy/spherely/discussions) | +[Releases](https://github.com/benbovy/spherely/releases) + +## Contents + +```{toctree} +:maxdepth: 1 + +install +api +``` + +## Acknowledgment + +The development of this project has been supported by two +[NumFOCUS] Small Development Grants (GeoPandas 2022 round +1 and GeoPandas 2023 round 3). + +[Shapely]: https://shapely.readthedocs.io +[s2geometry]: https://s2geometry.io +[s2geography]: https://github.com/paleolimbot/s2geography +[GEOS]: https://libgeos.org +[NumFOCUS]: https://numfocus.org diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 0ad07a9..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -Spherely Documentation -====================== - -Manipulation and analysis of geometric objects on the sphere. - -Spherely is the counterpart of `Shapely`_ (2.0+) for manipulation and analysis -of spherical geometric objects. It is using the widely deployed open-source -geometry library `s2geometry`_ via the library `s2geography`_ which provides a -`GEOS`_ compatibility layer on top of s2geometry. - -This library is at an early stage of development. - -Contents --------- - -.. toctree:: - :maxdepth: 2 - - api - -.. links - -.. _`Shapely`: https://shapely.readthedocs.io -.. _`s2geometry`: https://s2geometry.io -.. _`s2geography`: https://github.com/paleolimbot/s2geography -.. _`GEOS`: https://libgeos.org - -Get in touch ------------- - -The source repository is on GitHub: https://github.com/benbovy/spherely diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..20cbd04 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,104 @@ +(install)= + +# Installation + +## Built distributions + +The easiest way to install Spherely is via its binary packages available for +Linux, MacOS, and Windows platforms on [conda-forge](https://conda-forge.org/) +and [PyPI](https://pypi.org/project/spherely/). + +### Installation of Python binary wheels (PyPI) + +Install the last released binary wheel, e.g., using [pip](https://pip.pypa.io/): + +``` sh +$ pip install spherely +``` + +### Installation of Conda packages (conda-forge) + +Install the last released conda-forge package using +[conda](https://docs.conda.io/projects/conda/en/stable/): + +``` sh +$ conda install spherely --channel conda-forge +``` + +## Installation from source + +Compiling and installing Spherely from source may be useful for development +purpose and/or for building it against a specific version of S2Geography and/or +S2Geometry. + +### Requirements + +- Python +- Numpy +- [s2geography](https://github.com/paleolimbot/s2geography) v0.2.0 or higher +- [s2geometry](https://github.com/google/s2geometry) v0.11.1 or higher + +Additional build dependencies: + +- C++ compiler supporting C++17 standard +- CMake +- [scikit-build-core](https://github.com/scikit-build/scikit-build-core) + +### Setting up a development environment using conda + +All the requirements listed above are available via conda-forge. + +After cloning Spherely's [source +repository](https://github.com/benbovy/spherely), create a conda environment +with the required (and development) dependencies using the +`ci/environment-dev.yml` file: + +```sh +$ conda env create -f spherely/ci/environment-dev.yml +$ conda activate spherely-dev +``` + +Build and install Spherely: + +```sh +$ cd spherely +$ python -m pip install . -v --no-build-isolation +``` + +Note that you can specify a build directory in order to avoid rebuilding the +whole library from scratch each time after editing the code: + +```sh +$ python -m pip install . -v --no-build-isolation --config-settings build-dir=build/skbuild +``` + +Run the tests: + +```sh +$ pytest . -v +``` + +Spherely also uses [pre-commit](https://pre-commit.com/) for code +auto-formatting and linting at every commit. After installing it, you can enable +pre-commit hooks with the following command: + +```sh +$ pre-commit install +``` + +(Note: you can skip the pre-commit checks with `git commit --no-verify`) + +### Using the latest S2Geography version + +If you want to compile Spherely against the latest version of S2Geography, use: + + ```sh + $ git clone https://github.com/paleolimbot/s2geography + $ cmake \ + $ -S s2geography \ + $ -B s2geography/build \ + $ -DCMAKE_CXX_STANDARD=17 \ + $ -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX + $ cmake --build s2geography/build + $ cmake --install s2geography/build + ```