diff --git a/docs/Makefile b/docs/Makefile
index 4baff4b7..9ba49dc4 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -56,6 +56,7 @@ clean:
 .PHONY: html
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	touch $(BUILDDIR)/html/.nojekyll
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
@@ -217,7 +218,7 @@ pseudoxml:
 
 .PHONY: apidocs
 apidocs:
-	sphinx-apidoc -f -e -T -M -o . ../rasterio ../rasterio/rio ../rasterio/compat.py ../rasterio/tools ../rasterio/tool.py
+	sphinx-apidoc -f -e -T -o . ../rasterio ../rasterio/rio
 
 .PHONY: publish
 publish: html
diff --git a/docs/_build/html/.nojekyll b/docs/_build/html/.nojekyll
index f257b09f..e69de29b 100644
--- a/docs/_build/html/.nojekyll
+++ b/docs/_build/html/.nojekyll
@@ -1 +0,0 @@
-# Not a Jekyll site
diff --git a/docs/conf.py b/docs/conf.py
index ffdee8ca..8d2a53c4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -30,6 +30,7 @@ import os
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
diff --git a/docs/migrating-to-v1.rst b/docs/migrating-to-v1.rst
index 13f058e8..bfcf5228 100644
--- a/docs/migrating-to-v1.rst
+++ b/docs/migrating-to-v1.rst
@@ -72,13 +72,13 @@ Tickets
 
 
 I/O Operations
---------------
+~~~~~~~~~~~~~~
 
 Methods related to reading band data and dataset masks have changed in 1.0.
 
 
 Deprecated: ``rasterio.drivers()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 Previously users could register GDAL's drivers and open a datasource with:
 
@@ -173,7 +173,7 @@ dataset windows have been moved to ``rasterio.windows.*``:
 * ``rasterio.windows_intersect()``
 
 Tickets
-~~~~~~~
+```````
 
 * `#609 <https://github.com/mapbox/rasterio/pull/609>`__ - Introduction of
   ``rasterio.windows``.
@@ -193,7 +193,7 @@ several different locations:
     rasterio.tool.main()      -> rasterio.rio.insp.main()
 
 Tickets
-~~~~~~~
+```````
 
 * `#609 <https://github.com/mapbox/rasterio/pull/609>`__ - Deprecation of
   ``rasterio.tool``.
@@ -211,7 +211,7 @@ several different locations:
      rasterio.tools.merge.merge() -> rasterio.merge.merge()
 
 Tickets
-~~~~~~~
+```````
 
 * `#609 <https://github.com/mapbox/rasterio/pull/609>`__ - Deprecation of
   ``rasterio.tools``.
diff --git a/docs/modules.rst b/docs/modules.rst
deleted file mode 100644
index e7356de9..00000000
--- a/docs/modules.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-rasterio
-========
-
-.. toctree::
-   :maxdepth: 4
-
-   rasterio
diff --git a/docs/rasterio.aws.rst b/docs/rasterio.aws.rst
deleted file mode 100644
index d46aebb8..00000000
--- a/docs/rasterio.aws.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-rasterio.aws module
-===================
-
-.. automodule:: rasterio.aws
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/docs/rasterio.compat.rst b/docs/rasterio.compat.rst
new file mode 100644
index 00000000..d01b1234
--- /dev/null
+++ b/docs/rasterio.compat.rst
@@ -0,0 +1,7 @@
+rasterio.compat module
+======================
+
+.. automodule:: rasterio.compat
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/rasterio.drivers.rst b/docs/rasterio.drivers.rst
new file mode 100644
index 00000000..f09c2610
--- /dev/null
+++ b/docs/rasterio.drivers.rst
@@ -0,0 +1,7 @@
+rasterio.drivers module
+=======================
+
+.. automodule:: rasterio.drivers
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/rasterio.io.rst b/docs/rasterio.io.rst
new file mode 100644
index 00000000..3dadcb28
--- /dev/null
+++ b/docs/rasterio.io.rst
@@ -0,0 +1,7 @@
+rasterio.io module
+==================
+
+.. automodule:: rasterio.io
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/rasterio.rst b/docs/rasterio.rst
index 85986e61..cf4a16a6 100644
--- a/docs/rasterio.rst
+++ b/docs/rasterio.rst
@@ -1,24 +1,22 @@
 rasterio package
 ================
 
-.. automodule:: rasterio
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 Submodules
 ----------
 
 .. toctree::
 
+   rasterio.compat
    rasterio.coords
    rasterio.crs
+   rasterio.drivers
    rasterio.dtypes
    rasterio.enums
    rasterio.env
    rasterio.errors
    rasterio.features
    rasterio.fill
+   rasterio.io
    rasterio.mask
    rasterio.merge
    rasterio.plot
@@ -29,3 +27,10 @@ Submodules
    rasterio.warp
    rasterio.windows
 
+Module contents
+---------------
+
+.. automodule:: rasterio
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/rasterio.tool.rst b/docs/rasterio.tool.rst
deleted file mode 100644
index 7741b323..00000000
--- a/docs/rasterio.tool.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-rasterio.tool module
-====================
-
-.. automodule:: rasterio.tool
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/docs/rasterio.tools.mask.rst b/docs/rasterio.tools.mask.rst
deleted file mode 100644
index 96bbf33b..00000000
--- a/docs/rasterio.tools.mask.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-rasterio.tools.mask module
-==========================
-
-.. automodule:: rasterio.tools.mask
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/docs/rasterio.tools.merge.rst b/docs/rasterio.tools.merge.rst
deleted file mode 100644
index 04d5d231..00000000
--- a/docs/rasterio.tools.merge.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-rasterio.tools.merge module
-===========================
-
-.. automodule:: rasterio.tools.merge
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/docs/rasterio.tools.rst b/docs/rasterio.tools.rst
deleted file mode 100644
index 7582796c..00000000
--- a/docs/rasterio.tools.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-rasterio.tools package
-======================
-
-.. automodule:: rasterio.tools
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Submodules
-----------
-
-.. toctree::
-
-   rasterio.tools.mask
-   rasterio.tools.merge
-
diff --git a/docs/rasterio.warnings.rst b/docs/rasterio.warnings.rst
deleted file mode 100644
index 348ba4b9..00000000
--- a/docs/rasterio.warnings.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-rasterio.warnings module
-========================
-
-.. automodule:: rasterio.warnings
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/docs/topics.rst b/docs/topics.rst
index 3aaad397..391f4254 100644
--- a/docs/topics.rst
+++ b/docs/topics.rst
@@ -20,4 +20,6 @@ General Concepts
     georeferencing
     windowed-rw
     vsi
+    masking-by-shapefile
+    migrating-to-v1