clean up of documentation files

docs/Makefile

@@ -19,14 +19,15 @@ default: html
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  texinfo   to make Texinfo files"
-	@echo "  info      to make Texinfo files and run them through makeinfo"
-	@echo "  changes   to make an overview over all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
+	@echo "  html        standalone HTML files"
+	@echo "  html_noapi  same as above, without the time consuming API docs"
+	@echo "  pickle      pickle files (usable by e.g. sphinx-web)"
+	@echo "  htmlhelp    HTML files and a HTML help project"
+	@echo "  latex       LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  texinfo     Texinfo files"
+	@echo "  info        Texinfo files and run them through makeinfo"
+	@echo "  changes     an overview over all changed/added/deprecated items"
+	@echo "  linkcheck   check all external links for integrity (takes a long time)"
 	@echo
 	@echo "Compound utility targets:"
 	@echo "pdf          latex and then runs the PDF generation"

docs/README.rst

@@ -1,14 +1,32 @@
-Current version information
----------------------------
+IPython Documentation
+---------------------
 
-Please open manual.pdf for a PDF version of IPython's user manual, or go to
-the manual/ directory for an HTML version.
+This directory contains the majority of the documentation for IPython. 
+
+Requirements
+------------
+The following tools are needed to build the documentation:
+
+sphinx
+
+On Debian-based systems, you should be able to run::
+
+    sudo apt-get install sphinx 
+
+The documentation gets built using ``make``, and comes in several flavors.
+
+``make html`` - build the API and narrative documentation web pages, this
+is the the default ``make`` target, so running just ``make`` is equivalent to
+``make html``. 
+
+``make html_noapi`` - same as above, but without running the auto-generated
+API docs. When you are working on the narrative documentation, the most time
+consuming portion  of the build process is the processing and rending of the
+API documentation. This build target skips that.
+
+``make pdf`` will compile a pdf from the documentation.
+
+You can run ``make help`` to see information on all possible make targets.
 
 
-Bugs and future developments
-----------------------------
 
-The new_design.pdf document is a description of the goals for IPython's future
-development.  It includes a TODO/bugs section listing all currently known bugs
-in IPython.  Please report any bug you encounter if it is not already listed
-there.