sphinx docs, take one

docs/Makefile

@@ -0,0 +1,216 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/rasterio.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/rasterio.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/rasterio"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/rasterio"
+	@echo "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/api_docs.rst

@@ -0,0 +1,5 @@
+=================
+API Documentation
+=================
+
+.. automodule:: rasterio

docs/calc.rst

@@ -13,7 +13,7 @@ Expressions
 
 Rio-calc expressions look like
 
-.. code-block::
+.. code-block:: console
 
     (func|operator arg [*args])
 

docs/cli.rst

@@ -1,5 +1,20 @@
-Command Line Interface
-======================
+==================================
+Command Line Interface User Manual
+==================================
+
+Intro
+=====
+
+Design
+======
+
+
+.. toctree::
+
+    calc
+
+Commands
+========
 
 Rasterio's command line interface is a program named "rio".
 

docs/color.rst

@@ -1,5 +1,11 @@
+Color
+*****
+
+color interpretation
+--------------------
+
 Colormaps
-=========
+---------
 
 Writing colormaps
 -----------------

docs/community.rst

@@ -0,0 +1,9 @@
+=========
+Community
+=========
+
+[pic of sprint]
+Who uses it and for what?
+Code of conduct
+Contribution guidelines
+

docs/concurrency.rst

@@ -1,5 +1,5 @@
 Concurrent processing
-=====================
+*********************
 
 Rasterio affords concurrent processing of raster data. The Python GIL is
 released when calling GDAL's ``GDALRasterIO()`` function, which means that

docs/conf.py

@@ -0,0 +1,366 @@
+# -*- coding: utf-8 -*-
+#
+# rasterio documentation build configuration file, created by
+# sphinx-quickstart on Thu Mar 17 07:05:00 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'rasterio'
+copyright = u'2016, Mapbox'
+author = u'Sean Gillies'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'1.0'
+# The full version, including alpha/beta/rc tags.
+release = u'1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'rasteriodoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'rasterio.tex', u'rasterio Documentation',
+     u'Sean Gillies', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'rasterio', u'rasterio Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'rasterio', u'rasterio Documentation',
+     author, 'rasterio', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+# -- Options for Epub output ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = project
+
+# The HTML theme for the epub output. Since the default themes are not
+# optimized for small screen space, using the same theme for HTML and epub
+# output is usually not wise. This defaults to 'epub', a theme designed to save
+# visual space.
+#epub_theme = 'epub'
+
+# The language of the text. It defaults to the language option
+# or 'en' if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files that should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the Pillow.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'https://docs.python.org/': None}

docs/cookbook.rst

@@ -0,0 +1,3 @@
+=================
+Rasterio Cookbook
+=================

docs/data_model.rst

@@ -0,0 +1,6 @@
+Data Model
+==========
+
+Design Decisions
+Relationship to GDAL
+

docs/datasets_ndarrays.rst

@@ -1,12 +1,13 @@
 Datasets and ndarrays
 =====================
 
+
 Dataset objects provide read, read-write, and write access to raster data files
 and are obtained by calling ``rasterio.open()``. That function mimics Python's
 built-in ``open()`` and the dataset objects it returns mimic Python ``file``
 objects.
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> import rasterio
     >>> dataset = rasterio.open('tests/data/RGB.byte.tif')
@@ -22,7 +23,7 @@ objects.
 If you attempt to access a nonexistent path, ``rasterio.open()`` does the same
 thing as ``open()``, raising an exception immediately.
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> open('/lol/wut.tif')
     Traceback (most recent call last):
@@ -43,7 +44,7 @@ driver used. The ``height`` and ``width`` are the number of rows and columns of
 the raster dataset and ``shape`` is a ``height, width`` tuple as used by
 Numpy. The ``count`` attribute tells you the number of bands in the dataset.
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> dataset.driver
     u'GTiff'
@@ -59,7 +60,7 @@ that their pixels map to regions of the Earth. A dataset has a coordinate
 reference system and an affine transformation matrix that maps pixel
 coordinates to coordinates in that reference system.
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> dataset.crs
     {u'units': u'm', u'no_defs': True, u'ellps': u'WGS84', u'proj': u'utm', u'zone': 18}
@@ -71,7 +72,7 @@ To get the ``x, y`` world coordinates for the upper left corner of any pixel,
 take the product of the affine transformation matrix and the tuple ``(col,
 row)``.  
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> col, row = 0, 0
     >>> src.affine * (col, row)
@@ -83,11 +84,24 @@ row)``.
 Reading data
 ------------
 
+.. todo::
+
+    drivers
+    vsi (link)
+    context manager
+    ndarray = [band, cols, rows]
+    tags
+    profile
+    crs
+    transforms
+    dtypes
+    block windows
+
 Datasets generally have one or more bands (or layers). Following the GDAL
 convention, these are indexed starting with the number 1. The first band of
 a file can be read like this:
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> dataset.read(1)
     array([[0, 0, 0, ..., 0, 0, 0],
@@ -103,7 +117,7 @@ that array at the Python prompt is just a summary; the GeoTIFF file that
 Rasterio uses for testing has 0 values in the corners, but has nonzero values
 elsewhere.
 
-.. code-block::
+.. code-block:: python
 
     >>> from matplotlib import pyplot
     >>> pyplot.imshow(dataset.read(1), cmap='pink')
@@ -115,7 +129,7 @@ elsewhere.
 The indexes, Numpy data types, and nodata values of all a dataset's bands can
 be had from its ``indexes``, ``dtypes``, and ``nodatavals`` attributes.
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> for i, dtype, ndval in zip(src.indexes, src.dtypes, src.nodatavals):
     ...     print i, dtype, nodataval
@@ -126,7 +140,7 @@ be had from its ``indexes``, ``dtypes``, and ``nodatavals`` attributes.
 
 To close a dataset, call its ``close()`` method.
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> dataset.close()
     >>> dataset
@@ -134,7 +148,7 @@ To close a dataset, call its ``close()`` method.
 
 After it's closed, data can no longer be read.
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> dataset.read(1)
     Traceback (most recent call last):
@@ -143,7 +157,7 @@ After it's closed, data can no longer be read.
 
 This is the same behavior as Python's ``file``.
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> f = open('README.rst')
     >>> f.close()
@@ -157,7 +171,7 @@ and exit from runtime contexts created using a ``with`` statement. This
 ensures that files are closed no matter what exceptions may be raised within
 the the block.
 
-.. code-block:: pycon
+.. code-block:: python
 
     >>> with rasterio.open('tests/data/RGB.byte.tif', 'r') as one:
     ...     with rasterio.open('tests/data/RGB.byte.tif', 'r') as two:
@@ -170,14 +184,29 @@ the the block.
     <closed RasterReader name='tests/data/RGB.byte.tif' mode='r'>
     <closed RasterReader name='tests/data/RGB.byte.tif' mode='r'>
 
+Profile
+-------
+
 Writing data
 ------------
 
+.. todo::
+
+    ALL THE DETAILS
+    drivers
+    context manager
+    write 3d vs write 2d
+    profile.update
+    appending to existing data
+    transforms
+    dtypes
+    block windows
+
 Opening a file in writing mode is a little more complicated than opening
 a text file in Python. The dimensions of the raster dataset, the 
 data types, and the specific format must be specified.
 
-.. code-block:: pycon
+.. code-block:: python
 
    >>> with rasterio.oepn
 

docs/errors.rst

@@ -0,0 +1,2 @@
+Error Handling
+**************

docs/features.rst

@@ -1,5 +1,5 @@
-Features
-========
+Vector Features
+***************
 
 Rasterio's ``features`` module provides functions to extract shapes of raster
 features and to create new features by "burning" shapes into rasters:

docs/fillnodata.rst

@@ -0,0 +1,2 @@
+Filling nodata areas
+********************

docs/georeferencing.rst

@@ -1,5 +1,5 @@
 Georeferencing
-==============
+**************
 
 There are two parts to the georeferencing of raster datasets: the definition
 of the local, regional, or global system in which a raster's pixels are

docs/image_options.rst

@@ -1,6 +1,8 @@
-Options
-=======
+Image Options
+*************
 
+Driver Options
+-----------------
 GDAL's format drivers have many [configuration
 options](https://trac.osgeo.org/gdal/wiki/ConfigOptions) The way to set options
 for rasterio is via ``rasterio.drivers()``. Options set on entering are deleted
@@ -20,3 +22,16 @@ on exit.
 Use native Python forms (``True`` and ``False``) for boolean options. Rasterio
 will convert them GDAL's internal forms.
 
+
+Creation options
+-----------------
+
+Blocksize
+tiled
+
+Compression
+-----------
+
+Interleaving
+------------
+

docs/image_processing.rst

@@ -0,0 +1,5 @@
+Interoperability
+****************
+
+skimage and image processing software
+-------------------------------------

docs/index.rst

@@ -0,0 +1,47 @@
+.. rasterio documentation master file, created by
+   sphinx-quickstart on Thu Mar 17 07:05:00 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Rasterio Documentation
+======================
+
+Rasterio is for Python programmers and command line users
+who want to read, write and manipulate geospatial raster datasets.
+
+Rasterio employs GDAL under the hood for file I/O and raster formatting. Its functions typically accept and return Numpy ndarrays. Rasterio is designed to make working with geospatial raster data more productive and more fun.
+
+You can download from pypi and todo quick link to install
+
+.. code::
+
+    pip install rasterio
+
+And a quick example 
+
+.. code::
+
+    import rasterio
+    with rasterio.open('data.tif') as src:
+        array = src.read() 
+
+Contents:
+
+.. toctree::
+   :maxdepth: 3
+
+   python_manual
+   cli
+   api_docs
+   cookbook
+   community
+
+
+ 
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

docs/installation.rst

@@ -0,0 +1,2 @@
+Installation
+============

docs/intro.rst

@@ -0,0 +1,7 @@
+Introduction
+=============
+
+For Python devs
+CLI look to CLI users manual 
+What and what it does NOT do
+

docs/masks.rst

@@ -1,5 +1,5 @@
 Masks
-=====
+*****
 
 In using Rasterio, you'll encounter two different kinds of masks. One is the
 the valid data mask from GDAL, an unsigned byte array with the same number of
@@ -105,7 +105,7 @@ copy of the test data opened using rio-insp in "r+" (update) mode.
 To mark that all pixels of all bands are valid (i.e., to override nodata
 metadata values that can't be unset), you'd do this.
 
-.. code-block::
+.. code-block:: python
 
     >>> src.write_mask(True)
     >>> src.read_masks(1).all()

docs/nodata.rst

@@ -0,0 +1,2 @@
+Nodata
+******

docs/osgeo_gdal_migration.rst

@@ -0,0 +1,4 @@
+Migration Guide for osgeo.gdal users
+====================================
+
+A gentle nudge to switch

docs/overviews.rst

@@ -0,0 +1,2 @@
+Overviews
+*********

docs/plotting.rst

@@ -0,0 +1,2 @@
+Plotting
+********

docs/python_manual.rst

@@ -0,0 +1,12 @@
+==================
+Python User Manual
+==================
+
+.. toctree::
+
+    intro
+    installation
+    data_model
+    datasets_ndarrays
+    topics
+    osgeo_gdal_migration

docs/reproject.rst

@@ -1,5 +1,7 @@
 Reprojection
-============
+************
+
+TODO calc_default_transform
 
 Rasterio can map the pixels of a destination raster with an associated
 coordinate reference system and transform to the pixels of a source image with

docs/resampling.rst

@@ -0,0 +1,2 @@
+Resampling Methods
+******************

docs/tags.rst

@@ -1,5 +1,5 @@
 Tagging datasets and bands
-==========================
+**************************
 
 GDAL's `data model <http://www.gdal.org/gdal_datamodel.html>`__ includes
 collections of key, value pairs for major classes. In that model, these are

docs/topics.rst

@@ -0,0 +1,23 @@
+Topics
+======
+
+.. toctree::
+
+    reproject
+    errors
+    color
+    concurrency
+    image_options
+    fillnodata
+    overviews
+    plotting
+    features
+    masks
+    nodata
+    image_processing
+    resampling
+    tags
+    georeferencing
+    windowed-rw
+    vsi
+

docs/vsi.rst

@@ -0,0 +1,4 @@
+Virtual Files
+*************
+
+Support for zip, s3, etc

docs/windowed-rw.rst

@@ -1,5 +1,5 @@
 Windowed reading and writing
-============================
+****************************
 
 Beginning in rasterio 0.3, you can read and write "windows" of raster files.
 This feature allows you to operate on rasters that are larger than your