From df97ddfff9781e41b7e251770fbbae4232cfb708 Mon Sep 17 00:00:00 2001 From: Benoit Bovy Date: Wed, 11 Dec 2024 12:24:21 +0100 Subject: [PATCH 1/6] add install section + reformat index --- docs/conf.py | 17 +++++--- docs/index.md | 42 ++++++++++++++++++++ docs/index.rst | 31 --------------- docs/install.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 155 insertions(+), 37 deletions(-) create mode 100644 docs/index.md delete mode 100644 docs/index.rst create mode 100644 docs/install.md 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/index.md b/docs/index.md new file mode 100644 index 0000000..5922ea5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,42 @@ +# 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 + +- {doc}`install` +- {doc}`api` + +```{toctree} +:hidden: true +: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..f205aec --- /dev/null +++ b/docs/install.md @@ -0,0 +1,102 @@ +(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 binary wheel, e.g., using [pip](https://pip.pypa.io/): + +``` sh +$ pip install spherely +``` + +### Installation of Conda packages (conda-forge) + +Install the 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 using a specific version of S2Geography 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 +using the `ci/environment.yml` file with the required dependencies: + +```sh +$ conda env create -f spherely/ci/environment.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 + ``` From 74e88baebdce759c6a33a3c805a3decdd7e8a31d Mon Sep 17 00:00:00 2001 From: Benoit Bovy Date: Wed, 11 Dec 2024 12:25:05 +0100 Subject: [PATCH 2/6] doc environment: update pins Avoid issues in new versions of pydata-sphinx-theme or sphinx-book-theme, e.g., https://github.com/pydata/pydata-sphinx-theme/issues/2067 --- docs/environment.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 From 8c5a42ed7fff7e61e87a7c860d5c102b2477a658 Mon Sep 17 00:00:00 2001 From: Benoit Bovy Date: Wed, 11 Dec 2024 12:26:08 +0100 Subject: [PATCH 3/6] update README --- README.md | 81 +++++++++++++++---------------------------------------- 1 file changed, 22 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 7ba6665..6cd556a 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. -``` -$ 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). From 61841b1fe68128fa5bb8dc6fe050c93c80c8a13f Mon Sep 17 00:00:00 2001 From: Benoit Bovy Date: Wed, 11 Dec 2024 12:38:22 +0100 Subject: [PATCH 4/6] update CI Check links in markdown files. --- .../workflows/{lint.yaml => ci-additional.yml} | 18 ++++++++++++++---- .github/workflows/run-tests.yaml | 6 +++--- 2 files changed, 17 insertions(+), 7 deletions(-) rename .github/workflows/{lint.yaml => ci-additional.yml} (69%) 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 From 816ee9197b4d68cb04364e8764505750234e956c Mon Sep 17 00:00:00 2001 From: Benoit Bovy Date: Wed, 11 Dec 2024 12:57:39 +0100 Subject: [PATCH 5/6] minor tweaks --- docs/index.md | 4 ---- docs/install.md | 18 ++++++++++-------- 2 files changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/index.md b/docs/index.md index 5922ea5..4303566 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,11 +18,7 @@ geometry library [s2geometry] via the library [s2geography] which provides a ## Contents -- {doc}`install` -- {doc}`api` - ```{toctree} -:hidden: true :maxdepth: 1 install diff --git a/docs/install.md b/docs/install.md index f205aec..20cbd04 100644 --- a/docs/install.md +++ b/docs/install.md @@ -10,7 +10,7 @@ and [PyPI](https://pypi.org/project/spherely/). ### Installation of Python binary wheels (PyPI) -Install the binary wheel, e.g., using [pip](https://pip.pypa.io/): +Install the last released binary wheel, e.g., using [pip](https://pip.pypa.io/): ``` sh $ pip install spherely @@ -18,7 +18,7 @@ $ pip install spherely ### Installation of Conda packages (conda-forge) -Install the conda-forge package using +Install the last released conda-forge package using [conda](https://docs.conda.io/projects/conda/en/stable/): ``` sh @@ -28,7 +28,8 @@ $ conda install spherely --channel conda-forge ## Installation from source Compiling and installing Spherely from source may be useful for development -purpose and/or for using a specific version of S2Geography or S2Geometry. +purpose and/or for building it against a specific version of S2Geography and/or +S2Geometry. ### Requirements @@ -49,14 +50,15 @@ 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 -using the `ci/environment.yml` file with the required dependencies: +with the required (and development) dependencies using the +`ci/environment-dev.yml` file: ```sh -$ conda env create -f spherely/ci/environment.yml +$ conda env create -f spherely/ci/environment-dev.yml $ conda activate spherely-dev ``` -Build and install `spherely`: +Build and install Spherely: ```sh $ cd spherely @@ -86,9 +88,9 @@ $ pre-commit install (Note: you can skip the pre-commit checks with `git commit --no-verify`) -### Using the latest s2geography version +### Using the latest S2Geography version -If you want to compile spherely against the latest version of s2geography, use: +If you want to compile Spherely against the latest version of S2Geography, use: ```sh $ git clone https://github.com/paleolimbot/s2geography From 795e60309496e08ac78e2f60c8fffb949713dc64 Mon Sep 17 00:00:00 2001 From: Benoit Bovy Date: Fri, 13 Dec 2024 10:27:34 +0100 Subject: [PATCH 6/6] Update README.md Add link to documentation for installation from source instructions. Co-authored-by: Joris Van den Bossche --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6cd556a..132c0a0 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ $ conda install spherely --channel conda-forge ``` To compile and install Spherely from source, see detailed instructions in the -documentation. +[documentation](https://spherely.readthedocs.io/en/latest/install.html). ## Documentation