DOC: add installation section (#92)

* add install section + reformat index

* doc environment: update pins

Avoid issues in new versions of pydata-sphinx-theme or
sphinx-book-theme, e.g.,
pydata/pydata-sphinx-theme#2067

* update README

* update CI

Check links in markdown files.

* minor tweaks

* Update README.md

Add link to documentation for installation from source instructions.

Co-authored-by: Joris Van den Bossche <[email protected]>

---------

Co-authored-by: Joris Van den Bossche <[email protected]>

Author: benbovy

.github/workflows/lint.yaml renamed to .github/workflows/ci-additional.yml

@@ -4,19 +4,29 @@ 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:
         shell: bash -l {0}
 
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup micromamba
         uses: mamba-org/setup-micromamba@v1

.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

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).

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 <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"]

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

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