diff --git a/docs/source/api/snail.core.rst b/docs/source/api/snail.core.rst
index d2feba9..7fc87a1 100644
--- a/docs/source/api/snail.core.rst
+++ b/docs/source/api/snail.core.rst
@@ -5,14 +5,3 @@ snail.core package
    :members:
    :undoc-members:
    :show-inheritance:
-
-Submodules
-----------
-
-snail.core.intersections module
--------------------------------
-
-.. automodule:: snail.core.intersections
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/api/snail.rst b/docs/source/api/snail.rst
index c5990e9..d671599 100644
--- a/docs/source/api/snail.rst
+++ b/docs/source/api/snail.rst
@@ -25,6 +25,14 @@ snail.cli module
    :undoc-members:
    :show-inheritance:
 
+snail.damages module
+--------------------
+
+.. automodule:: snail.damages
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 snail.intersection module
 -------------------------
 
@@ -33,6 +41,14 @@ snail.intersection module
    :undoc-members:
    :show-inheritance:
 
+snail.io module
+---------------
+
+.. automodule:: snail.io
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 snail.routing module
 --------------------
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 88e048f..467b9e7 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -28,6 +28,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
+
 # Extra styles, found in _static
 def setup(app):
     app.add_css_file("theme_tweaks.css")
@@ -37,13 +38,12 @@ def setup(app):
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
-    "m2r2",
 ]
 templates_path = ["_templates"]
 exclude_patterns = []
 
 # The suffix(es) of source filenames.
-source_suffix = [".rst", ".md"]
+source_suffix = [".rst"]
 
 
 # -- Options for HTML output -------------------------------------------------
diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md
deleted file mode 100644
index 1f83562..0000000
--- a/docs/source/getting_started.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Getting Started
-
-For now, the best place to start is with the
-[notebook tutorials](https://github.com/nismod/snail/tree/master/tutorials).
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
new file mode 100644
index 0000000..6cefadc
--- /dev/null
+++ b/docs/source/getting_started.rst
@@ -0,0 +1,6 @@
+===============
+Getting Started
+===============
+
+For now, the best place to start is with the
+`notebook tutorials <https://github.com/nismod/snail/tree/master/tutorials>`_.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index ffd8f64..9b8a663 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -34,9 +34,58 @@ climate hazards on infrastructure networks.
     :alt: PyPI version
 
 
-.. mdinclude:: ../../README.md
-   :start-line: 22
-   :end-line: 95
+## Installation
+
+Install using pip:
+
+    pip install nismod-snail
+
+This should bring all dependencies with it. If any of these cause difficulties,
+try using a `conda <https://docs.conda.io/en/latest/miniconda.html>`_ environment::
+
+    conda env create -n snail_env \
+        python=3.8 geopandas shapely rasterio python-igraph
+    conda activate snail_env
+    pip install nismod-snail
+
+If all worked okay, you should be able to run python and import snail::
+
+    $ python
+    >>> import snail
+    >>> help(snail)
+    Help on package snail:
+
+    NAME
+        snail - snail - the spatial networks impact assessment library
+
+## Using the `snail` command
+
+Once installed, you can use `snail` directly from the command line.
+
+Split features on a grid defined by its transform, width and height::
+
+   snail split \
+      --features input.shp \
+      --transform 1 0 -180 0 -1 90 \
+      --width 360 \
+      --height 180 \
+      --output split.gpkg
+
+
+Split features on a grid defined by a GeoTIFF, optionally adding the values from each raster band to each split feature as a new attribute::
+
+   snail split \
+      --features lines.geojson \
+      --raster gridded_data.tif \
+      --attribute \
+      --output split_lines_with_raster_values.geojson
+
+
+Split multiple vector feature files along the grids defined by multiple raster files, attributing all raster values::
+
+   snail process -fs features.csv -rs rasters.csv
+
+Where at a minimum, each CSV has a column `path` with the path to each file.
 
 
 .. toctree::
diff --git a/pyproject.toml b/pyproject.toml
index 8d2e04d..5aa1011 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -45,7 +45,7 @@ dev = [
     "pytest-cov",
     "pytest",
 ]
-docs = ["sphinx", "m2r2"]
+docs = ["sphinx"]
 tutorials = [
     "contextily",
     "irv_autopkg_client",