Merge pull request wireservice#562 from nbedi/master

Break up docs for easier consumption

docs/about.rst

@@ -0,0 +1,31 @@
+===========
+About agate
+===========
+
+Why agate?
+==========
+
+* A readable and user-friendly API.
+* A complete set of SQL-like operations.
+* Unicode support everywhere.
+* Decimal precision everywhere.
+* Exhaustive user documentation.
+* Pluggable `extensions <extensions>`_ that add SQL integration, Excel support, and more.
+* Designed with `iPython <http://ipython.org/>`_, `Jupyter <https://jupyter.org/>`_ and `atom/hydrogen <https://atom.io/packages/hydrogen>`_ in mind.
+* Pure Python. No C dependencies to compile.
+* Exhaustive test coverage.
+* MIT licensed and free for all purposes.
+* Zealously `zen <https://www.python.org/dev/peps/pep-0020/>`_.
+
+Principles
+==========
+
+agate is a intended to fill a very particular programming niche. It should not be allowed to become as complex as `numpy <http://www.numpy.org/>`_ or `pandas <http://pandas.pydata.org/>`_. Please bear in mind the following principles when contemplating an addition:
+
+* Humans have less time than computers. Optimize for humans.
+* Most datasets are small. Don't optimize for "big data".
+* Text is data. It must always be a first-class citizen.
+* Python gets it right. Make it work like Python does.
+* Humans lives are nasty, brutish and short. Make it easy.
+* Mutability leads to confusion. Processes that alter data must create new copies.
+* Extensions are the way. Don't add it to core unless everybody needs it.

docs/contributing.rst

@@ -7,19 +7,6 @@ AUTHORS
 
 .. include:: ../AUTHORS.rst
 
-Principles
-==========
-
-agate is a intended to fill a very particular programming niche. It should not be allowed to become as complex as `numpy <http://www.numpy.org/>`_ or `pandas <http://pandas.pydata.org/>`_. Please bear in mind the following principles when contemplating an addition:
-
-* Humans have less time than computers. Optimize for humans.
-* Most datasets are small. Don't optimize for "big data".
-* Text is data. It must always be a first-class citizen.
-* Python gets it right. Make it work like Python does.
-* Humans lives are nasty, brutish and short. Make it easy.
-* Mutability leads to confusion. Processes that alter data must create new copies.
-* Extensions are the way. Don't add it to core unless everybody needs it.
-
 Process for contributing code
 =============================
 

docs/cookbook.rst

@@ -2,23 +2,57 @@
 Cookbook
 ========
 
+Welcome to the agate cookbook, a source of how-to's and use cases.
+
 .. toctree::
+    :hidden:
     :maxdepth: 2
 
     cookbook/create
     cookbook/save
     cookbook/filter
     cookbook/sort
     cookbook/search
-    cookbook/transform
     cookbook/statistics
     cookbook/compute
-    cookbook/rank
     cookbook/datetime
-    cookbook/locale
     cookbook/sql
     cookbook/excel
     cookbook/r
     cookbook/underscore
+    cookbook/rank
+    cookbook/locale
+    cookbook/transform
     cookbook/charting
     cookbook/misc
+
+Basics
+======
+
+* `Creating tables from various data types <cookbook/create.html>`_
+* `Saving data to various data types <cookbook/save.html>`_
+* `Filtering rows of data <cookbook/filter.html>`_
+* `Sorting rows of data <cookbook/sort.html>`_
+* `Searching through a table <cookbook/search.html>`_
+* `Calculating statistics <cookbook/statistics.html>`_
+* `Computing new columns <cookbook/compute.html>`_
+* `Handling dates and times <cookbook/datetime.html>`_
+
+Coming from other tools
+=======================
+
+* `SQL <cookbook/sql.html>`_
+* `Excel <cookbook/excel.html>`_
+* `R <cookbook/r.html>`_
+* `Underscore.js <cookbook/underscore.html>`_
+
+Advanced techniques
+===================
+
+* `Transforming data (pivot/normalize/denormalize) <cookbook/transform.html>`_
+* `Charting data <cookbook/charting.html>`_
+* `Specifying locale <cookbook/locale.html>`_
+* `Rank a sequence of data <cookbook/rank.html>`_
+* `Miscellaneous <cookbook/misc.html>`_
+
+If you believe a specific use case is missing from the above list, please `submit an issue <https://github.com/wireservice/agate/issues/new>`_ on the GitHub repository.

docs/index.rst

@@ -4,20 +4,30 @@ agate |release|
 
 .. include:: ../README.rst
 
-Why agate?
-==========
-
-* A readable and user-friendly API.
-* A complete set of SQL-like operations.
-* Unicode support everywhere.
-* Decimal precision everywhere.
-* Exhaustive user documentation.
-* Pluggable `extensions <extensions>`_ that add SQL integration, Excel support, and more.
-* Designed with `iPython <http://ipython.org/>`_, `Jupyter <https://jupyter.org/>`_ and `atom/hydrogen <https://atom.io/packages/hydrogen>`_ in mind.
-* Pure Python. No C dependencies to compile.
-* Exhaustive test coverage.
-* MIT licensed and free for all purposes.
-* Zealously `zen <https://www.python.org/dev/peps/pep-0020/>`_.
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+
+    about
+    install
+    tutorial
+    cookbook
+    extensions
+    api
+    contributing
+    release_process
+    license
+    changelog
+
+Show me docs
+============
+
+* `About <about.html>`_ - why you should use agate and principles behind its implementation
+* `Install <install.html>`_ - how to install for users and developers 
+* `Tutorial <tutorial.html>`_ - a step-by-step guide to start using agate
+* `Cookbook <cookbook.html>`_ - a list of use cases for new users, users coming from other tools and advanced users
+* `Extensions <extensions.html>`_ - how to make your own agate extensions and a list of existing extensions
+* `API <api.html>`_ - the technical documentation for every agate class and method in the source code
 
 Show me code
 ============
@@ -55,26 +65,6 @@ Show me code
 
 This example, complete with a detailed explanation, is available as a `Jupyter notebook <http://nbviewer.ipython.org/urls/gist.githubusercontent.com/onyxfish/36f459dab02545cbdce3/raw/534698388e5c404996a7b570a7228283344adbb1/example.py.ipynb>`_.
 
-Table of contents
-=================
-
-.. toctree::
-    :maxdepth: 2
-
-    install
-    tutorial
-    cookbook
-    extensions
-    api
-    contributing
-    release_process
-    changelog
-
-License
-=======
-
-.. include:: ../COPYING
-
 Indices and tables
 ==================
 

docs/license.rst

@@ -0,0 +1,5 @@
+=======
+License
+=======
+
+.. include:: ../COPYING