Properly organize toctrees. Closes wireservice#339.

Author: onyxfish

CHANGELOG

@@ -1,6 +1,7 @@
 1.0.0
 -----
 
+* Reorganize docs so TOC works better. (#339)
 * Render docs locally with RTD theme.
 * Fix header in "tricks" docs.
 * Add install instructions to tutorial. (#331)

docs/conf.py

@@ -68,7 +68,7 @@
 # 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']
+#html_static_path = ['_static']
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'csvkitdoc'

docs/contributing.rst

@@ -2,10 +2,26 @@
 Contributing to csvkit
 ======================
 
-Welcome!
-========
+Principles
+==========
+
+csvkit is to tabular data what the standard Unix text processing suite (grep, sed, cut, sort) is to text. As such, csvkit adheres to `the Unix philosophy <http://en.wikipedia.org/wiki/Unix_philosophy>`_.
+
+#. Small is beautiful.
+#. Make each program do one thing well.
+#. Build a prototype as soon as possible.
+#. Choose portability over efficiency.
+#. Store data in flat text files.
+#. Use software leverage to your advantage.
+#. Use shell scripts to increase leverage and portability.
+#. Avoid captive user interfaces.
+#. Make every program a filter.
+
+As there is no formally defined CSV format, csvkit encourages well-known formatting standards:
+
+* Output favors compatability with the widest range of applications. This means that quoting is done with double-quotes and only when necessary, columns are separated with commas, and lines are terminated with unix style line endings ("\\n").
 
-Thanks for your interest in contributing to csvkit. There is work be done by developers of all skill levels.
+* Data that is modified or generated will prefer consistency over brevity. Floats always include at least one decimal place, even if they are round. Dates and times are written in ISO8601 format.
 
 Process for contributing code
 =============================

docs/index.rst

@@ -58,173 +58,16 @@ Extract data from PostgreSQL:::
 
 And much more...
 
-.. _installation:
-
-Installation
-============
-
-Users
------
-
-csvkit is works on Python versions 2.6, 2.7, 3.3 and 3.4, as well as `PyPy <http://pypy.org/>`_. It is supported on OSX and Linux. It also works--but is tested less frequently--on Windows.
-
-Installing csvkit is simple::
-
-    pip install csvkit
-
-.. note::
-
-    If you are installing on Ubuntu you may need to install the Python development headers prior to install csvkit::
-
-        sudo apt-get install python-dev python-pip python-setuptools build-essential
-
-.. note:: 
-
-    If the installation appears to be successful but running the tools fails, try updating your version of Python setuptools::
-
-        pip install --upgrade setuptools
-        pip install --upgrade csvkit
-
-.. note::
-
-    If you are using Python2 and have a recent version of pip, you may need to run pip with the additional arguments :code:`--allow-external argparse`.
-
-Developers
-----------
-
-If you are a developer that also wants to hack on csvkit, install it this way::
-
-    git clone git://github.com/onyxfish/csvkit.git
-    cd csvkit
-    mkvirtualenv csvkit
-
-    # If running Python 2
-    pip install -r requirements-py2.txt
-
-    # If running Python 3
-    pip install -r requirements-py3.txt
-
-    python setup.py develop
-    tox
-
-Be sure to read the documentation below under the header :ref:`contributing`.
-    
-Tutorial
-========
-
-The csvkit tutorial walks through processing and analyzing a real dataset:
-
-.. toctree::
-    :maxdepth: 2 
-    :numbered:
-
-    tutorial/1_getting_started
-    tutorial/2_examining_the_data
-    tutorial/3_power_tools
-    tutorial/4_going_elsewhere
-
-Usage
-=====
-
-csvkit is comprised of a number of individual command line utilities that be loosely divided into a few major categories: Input, Processing, and Output. Documentation and examples for each utility are described on the following pages.
-
-*Input*
-
-.. toctree::
-    :maxdepth: 1 
-
-    scripts/in2csv
-    scripts/sql2csv
-
-*Processing*
+Table of contents
+=================
 
 .. toctree::
-    :maxdepth: 1 
-
-    scripts/csvclean
-    scripts/csvcut
-    scripts/csvgrep
-    scripts/csvjoin
-    scripts/csvsort
-    scripts/csvstack
-
-*Output (and Analysis)*
-   
-.. toctree::
-    :maxdepth: 1 
-
-    scripts/csvformat
-    scripts/csvjson
-    scripts/csvlook
-    scripts/csvpy
-    scripts/csvsql
-    scripts/csvstat
-
-*Appendices*
-
-.. toctree::
-    :maxdepth: 2 
-
-    common_arguments
-    tricks
-
-Using as a library
-==================
-
-csvkit is designed to be used a replacement for most of Python's :mod:`csv` module. Important parts of the API are documented on the following pages.
-
-Don't!
-
-::
-
-    import csv
-
-Do!
-
-::
-
-    import csvkit
-
-.. toctree::
-    :maxdepth: 1
-
-    api/csvkit
-    api/csvkit.py2
-    api/csvkit.py3
-    api/csvkit.unicsv
-    api/csvkit.sniffer
-
-Principles
-==========
-
-csvkit is to tabular data what the standard Unix text processing suite (grep, sed, cut, sort) is to text. As such, csvkit adheres to `the Unix philosophy <http://en.wikipedia.org/wiki/Unix_philosophy>`_.
-
-#. Small is beautiful.
-#. Make each program do one thing well.
-#. Build a prototype as soon as possible.
-#. Choose portability over efficiency.
-#. Store data in flat text files.
-#. Use software leverage to your advantage.
-#. Use shell scripts to increase leverage and portability.
-#. Avoid captive user interfaces.
-#. Make every program a filter.
-
-As there is no formally defined CSV format, csvkit encourages well-known formatting standards:
-
-* Output favors compatability with the widest range of applications. This means that quoting is done with double-quotes and only when necessary, columns are separated with commas, and lines are terminated with unix style line endings ("\\n").
-
-* Data that is modified or generated will prefer consistency over brevity. Floats always include at least one decimal place, even if they are round. Dates and times are written in ISO8601 format.
-
-.. _contributing:
-
-Contributing
-============
-
-Want to hack on csvkit? Here's how:
-
-.. toctree::
-    :maxdepth: 2
-
+    :maxdepth: 3 
+    
+    install
+    tutorial
+    cli 
+    lib
     contributing
     release 
 

docs/release.rst

@@ -2,9 +2,6 @@
 Release process
 ===============
 
-How to cut a csvkit release
-===========================
-
 #. Verify no `high priority issues <https://github.com/onyxfish/csvkit/issues?q=is%3Aopen+is%3Aissue+label%3A%22High+Priority%22>`_ are outstanding.
 #. Run the full test suite with fresh environments for all versions: ``tox -r`` (Everything MUST pass.)
 #. Ensure these files all have the correct version number:

docs/scripts/csvclean.rst

@@ -23,7 +23,7 @@ Cleans a CSV file of common syntax errors. Outputs [basename]_out.csv and [basen
                             created. Information about what would have been done
                             will be printed to STDERR.
 
-Also see: :doc:`common_arguments`.
+See also: :doc:`../common_arguments`.
 
 Examples
 ========

docs/scripts/csvcut.rst

@@ -30,7 +30,7 @@ Filters and truncates CSV files. Like unix "cut" command, but for tabular data::
 
 Note that csvcut does not include row filtering, for this you should pipe data to :doc:`csvgrep`.
 
-Also see: :doc:`common_arguments`.
+See also: :doc:`../common_arguments`.
 
 Examples
 ========

docs/scripts/csvformat.rst

@@ -43,7 +43,7 @@ Convert a CSV file to a custom output format.::
                             Character used to terminate lines in the output CSV
                             file. 
 
-Also see: :doc:`common_arguments`.
+See also: :doc:`../common_arguments`.
 
 Examples
 ========

docs/scripts/csvgrep.rst

@@ -37,7 +37,7 @@ Filter tabular data to only those rows where certain columns contain a given val
       -i, --invert-match    If specified, select non-matching instead of matching
                             rows.
 
-Also see: :doc:`common_arguments`.
+See also: :doc:`../common_arguments`.
 
 NOTE: Even though '-m', '-r', and '-f' are listed as "optional" arguments, you must specify one of them.
 

docs/scripts/csvjoin.rst

@@ -41,7 +41,7 @@ Merges two or more CSV tables together using a method analogous to SQL JOIN oper
     Note that the join operation requires reading all files into memory. Don't try
     this on very large files.
 
-Also see: :doc:`common_arguments`.
+See also: :doc:`../common_arguments`.
 
 Examples
 ========