From df97ddfff9781e41b7e251770fbbae4232cfb708 Mon Sep 17 00:00:00 2001 From: Benoit Bovy Date: Wed, 11 Dec 2024 12:24:21 +0100 Subject: [PATCH] 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 + ```