add install section + reformat index

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/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

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
+ ```