Begin the Great Refactoring of the docs.

* Move sphinx-build option description from intro to a new document.
* Move toctree information to a new document in markup/.
* Add a tutorial document placed after intro. Begin filling it in.

10 files changed, 340 insertions, 137 deletions

diff --git a/doc/conf.py b/doc/conf.py
index 7e220848..b0e847e7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -16,7 +16,6 @@ project = 'Sphinx'
 copyright = '2007-2010, Georg Brandl'
 version = sphinx.__released__
 release = version
-
 show_authors = True
 
 html_theme = 'sphinxdoc'
diff --git a/doc/contents.rst b/doc/contents.rst
index 3393f4a8..079f93f2 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -7,7 +7,8 @@ Sphinx documentation contents
    :maxdepth: 2
 
    intro
-   concepts
+   tutorial
+   invocation
    rest
    markup/index
    domains
diff --git a/doc/faq.rst b/doc/faq.rst
index 81204c08..1a993204 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -37,6 +37,8 @@ How do I...
    come through cleanly.
 
 
+.. _usingwith:
+
 Using Sphinx with...
 --------------------
 
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 0c7725b8..aa71b2b8 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -32,6 +32,19 @@ Glossary
 
       See :ref:`directives` for more information.
 
+   document name
+      Since reST source files can have different extensions (some people like
+      ``.txt``, some like ``.rst`` -- the extension can be configured with
+      :confval:`source_suffix`) and different OSes have different path separators,
+      Sphinx abstracts them: :dfn:`document names` are always relative to the
+      :term:`source directory`, the extension is stripped, and path separators
+      are converted to slashes.  All values, parameters and such referring to
+      "documents" expect such document names.
+
+      Examples for document names are ``index``, ``library/zipfile``, or
+      ``reference/datamodel/types``.  Note that there is no leading or trailing
+      slash.
+
    domain
       A domain is a collection of markup (reStructuredText :term:`directive`\ s
       and :term:`role`\ s) to describe and link to :term:`object`\ s belonging
@@ -50,6 +63,9 @@ Glossary
       parsing stage, so that successive runs only need to read and parse new and
       changed documents.
 
+   master document
+      The document that contains the root :dir:`toctree` directive.
+
    object
       The basic building block of Sphinx documentation.  Every "object
       directive" (e.g. :dir:`function` or :dir:`object`) creates such a block;
diff --git a/doc/intro.rst b/doc/intro.rst
index 37346b6f..d72cf360 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -35,6 +35,12 @@ to reStructuredText/Sphinx from other documentation systems.
   markup; it is at `Google Code <http://code.google.com/p/db2rst/>`_.
 
 
+Use with other systems
+----------------------
+
+See the :ref:`pertinent section in the FAQ list <usingwith>`.
+
+
 Prerequisites
 -------------
 
@@ -47,117 +53,8 @@ or some (not broken) SVN trunk snapshot.
 .. _Pygments: http://pygments.org
 
 
-Setting up the documentation sources
-------------------------------------
-
-The root directory of a documentation collection is called the :dfn:`source
-directory`.  Normally, this directory also contains the Sphinx configuration
-file :file:`conf.py`, but that file can also live in another directory, the
-:dfn:`configuration directory`.
-
-.. versionadded:: 0.3
-   Support for a different configuration directory.
-
-Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
-source directory and creates a default :file:`conf.py` from a few questions it
-asks you.  Just run ::
-
-   $ sphinx-quickstart
-
-and answer the questions.
-
-
-Running a build
----------------
-
-A build is started with the :program:`sphinx-build` script.  It is called
-like this::
-
-     $ sphinx-build -b latex sourcedir builddir
-
-where *sourcedir* is the :term:`source directory`, and *builddir* is the
-directory in which you want to place the built documentation (it must be an
-existing directory).  The :option:`-b` option selects a builder; in this example
-Sphinx will build LaTeX files.
-
-The :program:`sphinx-build` script has several more options:
-
-**-a**
-   If given, always write all output files.  The default is to only write output
-   files for new and changed source files.  (This may not apply to all
-   builders.)
-
-**-E**
-   Don't use a saved :term:`environment` (the structure caching all
-   cross-references), but rebuild it completely.  The default is to only read
-   and parse source files that are new or have changed since the last run.
-
-**-t** *tag*
-   Define the tag *tag*.  This is relevant for :dir:`only` directives that only
-   include their content if this tag is set.
-
-   .. versionadded:: 0.6
-
-**-d** *path*
-   Since Sphinx has to read and parse all source files before it can write an
-   output file, the parsed source files are cached as "doctree pickles".
-   Normally, these files are put in a directory called :file:`.doctrees` under
-   the build directory; with this option you can select a different cache
-   directory (the doctrees can be shared between all builders).
-
-**-c** *path*
-   Don't look for the :file:`conf.py` in the source directory, but use the given
-   configuration directory instead.  Note that various other files and paths
-   given by configuration values are expected to be relative to the
-   configuration directory, so they will have to be present at this location
-   too.
-
-   .. versionadded:: 0.3
-
-**-C**
-   Don't look for a configuration file; only take options via the ``-D`` option.
-
-   .. versionadded:: 0.5
-
-**-D** *setting=value*
-   Override a configuration value set in the :file:`conf.py` file.  The value
-   must be a string or dictionary value.  For the latter, supply the setting
-   name and key like this: ``-D latex_elements.docclass=scrartcl``.
-
-   .. versionchanged:: 0.6
-      The value can now be a dictionary value.
-
-**-A** *name=value*
-   Make the *name* assigned to *value* in the HTML templates.
-
-**-n**
-   Run in nit-picky mode.  Currently, this generates warnings for all missing
-   references.
-
-**-N**
-   Do not do colored output.  (On Windows, colored output is disabled in any
-   case.)
-
-**-q**
-   Do not output anything on standard output, only write warnings and errors to
-   standard error.
-
-**-Q**
-   Do not output anything on standard output, also suppress warnings.  Only
-   errors are written to standard error.
-
-**-w** *file*
-   Write warnings (and errors) to the given file, in addition to standard error.
-
-**-W**
-   Turn warnings into errors.  This means that the build stops at the first
-   warning and ``sphinx-build`` exits with exit status 1.
-
-**-P**
-   (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
-   unhandled exception occurs while building.
-
+Usage
+-----
 
-You can also give one or more filenames on the command line after the source and
-build directories.  Sphinx will then try to build only these output files (and
-their dependencies).
+See :doc:`the tutorial <tutorial>` for an introduction.  It also contains links
+to more advanced sections in this manual for the topics it discusses.
diff --git a/doc/invocation.rst b/doc/invocation.rst
new file mode 100644
index 00000000..10e2d04c
--- /dev/null
+++ b/doc/invocation.rst
@@ -0,0 +1,177 @@
+.. _invocation:
+
+sphinx-build Invocation
+=======================
+
+A build is started with the :program:`sphinx-build` script.  It is called like
+this::
+
+     $ sphinx-build [options] sourcedir builddir [filenames]
+
+where *sourcedir* is the :term:`source directory`, and *builddir* is the
+directory in which you want to place the built documentation (it must be an
+existing directory).
+
+The :program:`sphinx-build` script has several options:
+
+.. cmdoption:: -b buildername
+
+   Select a builder.  The most common builders are:
+
+   **html**
+      Build HTML pages.  This is the default builder.
+
+   **dirhtml**
+      Build HTML pages, but with a single directory per document.  Makes for
+      prettier URLs (no ``.html``) if served from a webserver.
+
+   **singlehtml**
+      Build a single HTML with the whole content.
+
+   **htmlhelp**, **qthelp**, **devhelp**, **epub**
+      Build HTML files with additional information for building a documentation
+      collection in one of these formats.
+
+   **latex**
+      Build LaTeX sources that can be compiled to a PDF document using
+      :program:`pdflatex`.
+
+   **man**
+      Build manual pages in groff format for UNIX systems.
+
+   **text**
+      Build plain text files.
+
+   **doctest**
+      Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
+      extension is enabled.
+
+   **linkcheck**
+      Check the integrity of all external links.
+
+   See :ref:`builders` for a list of all builders shipped with Sphinx.
+   Extensions can add their own builders.
+
+.. cmdoption:: -a
+
+   If given, always write all output files.  The default is to only write output
+   files for new and changed source files.  (This may not apply to all
+   builders.)
+
+.. cmdoption:: -E
+
+   Don't use a saved :term:`environment` (the structure caching all
+   cross-references), but rebuild it completely.  The default is to only read
+   and parse source files that are new or have changed since the last run.
+
+.. cmdoption:: -t tag
+
+   Define the tag *tag*.  This is relevant for :dir:`only` directives that only
+   include their content if this tag is set.
+
+   .. versionadded:: 0.6
+
+.. cmdoption:: -d path
+
+   Since Sphinx has to read and parse all source files before it can write an
+   output file, the parsed source files are cached as "doctree pickles".
+   Normally, these files are put in a directory called :file:`.doctrees` under
+   the build directory; with this option you can select a different cache
+   directory (the doctrees can be shared between all builders).
+
+.. cmdoption:: -c path
+
+   Don't look for the :file:`conf.py` in the source directory, but use the given
+   configuration directory instead.  Note that various other files and paths
+   given by configuration values are expected to be relative to the
+   configuration directory, so they will have to be present at this location
+   too.
+
+   .. versionadded:: 0.3
+
+.. cmdoption:: -C
+
+   Don't look for a configuration file; only take options via the ``-D`` option.
+
+   .. versionadded:: 0.5
+
+.. cmdoption:: -D setting=value
+
+   Override a configuration value set in the :file:`conf.py` file.  The value
+   must be a string or dictionary value.  For the latter, supply the setting
+   name and key like this: ``-D latex_elements.docclass=scrartcl``.  For boolean
+   values, use ``0`` or ``1`` as the value.
+
+   .. versionchanged:: 0.6
+      The value can now be a dictionary value.
+
+.. cmdoption:: -A name=value
+
+   Make the *name* assigned to *value* in the HTML templates.
+
+   .. versionadded:: 0.5
+
+.. cmdoption:: -n
+
+   Run in nit-picky mode.  Currently, this generates warnings for all missing
+   references.
+
+.. cmdoption:: -N
+
+   Do not emit colored output.  (On Windows, colored output is disabled in any
+   case.)
+
+.. cmdoption:: -q
+
+   Do not output anything on standard output, only write warnings and errors to
+   standard error.
+
+.. cmdoption:: -Q
+
+   Do not output anything on standard output, also suppress warnings.  Only
+   errors are written to standard error.
+
+.. cmdoption:: -w file
+
+   Write warnings (and errors) to the given file, in addition to standard error.
+
+.. cmdoption:: -W
+
+   Turn warnings into errors.  This means that the build stops at the first
+   warning and ``sphinx-build`` exits with exit status 1.
+
+.. cmdoption:: -P
+
+   (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
+   unhandled exception occurs while building.
+
+
+You can also give one or more filenames on the command line after the source and
+build directories.  Sphinx will then try to build only these output files (and
+their dependencies).
+
+
+Makefile options
+----------------
+
+The :file:`Makefile` and :file:`make.bat` files created by
+:program:`sphinx-quickstart` usually run :program:`sphinx-build` only with the
+:option:`-b` and :option:`-d` options.  However, they support the following
+variables to customize behavior:
+
+.. describe:: PAPER
+
+   The value for :confval:`latex_paper_size`.
+
+.. describe:: SPHINXBUILD
+
+   The command to use instead of ``sphinx-build``.
+
+.. describe:: BUILDDIR
+
+   The build directory to use instead of the one chosen in
+   :program:`sphinx-quickstart`.
+
+.. describe:: SPHINXOPTS
+
+   Additional options for :program:`sphinx-build`.
diff --git a/doc/markup/index.rst b/doc/markup/index.rst
index a39a71a8..f1bc27d1 100644
--- a/doc/markup/index.rst
+++ b/doc/markup/index.rst
@@ -8,6 +8,7 @@ markup.  This section contains the reference material for these facilities.
 
 .. toctree::
 
+   toctree
    desc
    para
    code
diff --git a/doc/concepts.rst b/doc/markup/toctree.rst
index b0040d8f..d85a0de0 100644
--- a/doc/concepts.rst
+++ b/doc/markup/toctree.rst
@@ -1,27 +1,8 @@
-.. highlight:: rest
-
-.. _concepts:
-
-Sphinx concepts
-===============
-
-Document names
---------------
-
-Since the reST source files can have different extensions (some people like
-``.txt``, some like ``.rst`` -- the extension can be configured with
-:confval:`source_suffix`) and different OSes have different path separators,
-Sphinx abstracts them: all "document names" are relative to the :term:`source
-directory`, the extension is stripped, and path separators are converted to
-slashes.  All values, parameters and suchlike referring to "documents" expect
-such a document name.
-
-Examples for document names are ``index``, ``library/zipfile``, or
-``reference/datamodel/types``.  Note that there is no leading slash.
-
+.. highlight:: rst
+.. _toctree-directive:
 
 The TOC tree
-------------
+============
 
 .. index:: pair: table of; contents
 
diff --git a/doc/more.png b/doc/more.png
new file mode 100644
index 00000000..3eb7b05c
--- /dev/null
+++ b/doc/more.png
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
new file mode 100644
index 00000000..a24d88e4
--- /dev/null
+++ b/doc/tutorial.rst
@@ -0,0 +1,129 @@
+.. highlight:: rst
+
+Sphinx Tutorial -- your first documentation
+===========================================
+
+This document is meant to give an overview of all common tasks while using
+Sphinx.  The green arrows designate "more info" links leading to advanced
+sections about the described task.
+
+
+Setting up the documentation sources
+------------------------------------
+
+The root directory of a documentation collection is called the :term:`source
+directory`.  This directory also contains the Sphinx configuration file
+:file:`conf.py`, where you can configure all aspects of how Sphinx reads your
+sources and builds your documentation.  [#]_
+
+Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
+source directory and creates a default :file:`conf.py` with the most useful
+configuration values from a few questions it asks you.  Just run ::
+
+   $ sphinx-quickstart
+
+and answer its questions.
+
+
+Adding some content
+-------------------
+
+Let's assume you've run :program:`sphinx-quickstart`.  It created a source
+directory with :file:`conf.py` and a master document, :file:`index.rst` (if you
+accepted the defaults).  The main function of the :term:`master document` is to
+serve as a welcome page, and to contain the root of the "table of contents tree"
+(or *toctree*).  This is one of the main things that Sphinx adds to
+reStructuredText, a way to connect multiple files to a single hierarchy of
+documents.
+
+.. sidebar:: reStructuredText directives
+
+   ``toctree`` is a reStructuredText :dfn:`directive`, a very versatile piece of
+   markup.  Directives can have arguments, options and content.
+
+   *Arguments* are given directly after the double colon following the
+   directive's name.  Each directive decides whether it can have arguments, and
+   how many.
+
+   *Options* are given after the arguments, in form of a "field list".  The
+   ``maxdepth`` is such an option for the ``toctree`` directive.
+
+   *Content* follows the options or arguments after a blank line.  Each
+   directive decides whether to allow content, and what to do with it.
+
+   A common gotcha with directives is that **the first line of the content must
+   be indented to the same level as the options are**.
+
+
+The toctree directive initially is empty, and looks like this::
+
+   .. toctree::
+      :maxdepth: 2
+
+You add documents listing them in the *content* of the directive::
+
+   .. toctree::
+      :maxdepth: 2
+
+      intro
+      tutorial
+      ...
+
+This is exactly how the toctree for this documentation looks.  The documents to
+include are given as :term:`document name`\ s, which in short means that you
+leave off the file name extension and use slashes as directory separators.
+
+|more| Read more about :ref:`the toctree directive <toctree-directive>`.
+
+You can now create the files you listed in the toctree, and their section titles
+will be inserted (up to the "maxdepth" level) at the place where the toctree
+directive is placed.  Also, Sphinx now knows about the order and hierarchy of
+your documents.  (They may contain ``toctree`` directives themselves, which
+means you can create deeply nested hierarchies if necessary.)
+
+
+Running the build
+-----------------
+
+A build is started with the :program:`sphinx-build` script.  It is called
+like this::
+
+   $ sphinx-build -b html sourcedir builddir
+
+where *sourcedir* is the :term:`source directory`, and *builddir* is the
+directory in which you want to place the built documentation.  The :option:`-b`
+option selects a builder; in this example Sphinx will build LaTeX files.
+
+However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a
+:file:`make.bat` which make life even easier for you:  with them you only need
+to run ::
+
+   $ make html
+
+to build HTML docs in the build directory you chose.
+
+|more| See :ref:`invocation` for all options that :program:`sphinx-build`
+supports.
+
+
+Topics to be covered
+--------------------
+
+- Autodoc
+- Domains
+- Basic configuration
+- Selecting a theme
+- Templating
+- Using extensions
+- Writing extensions
+
+
+.. rubric:: Footnotes
+
+.. [#] This is the usual lay-out.  However, :file:`conf.py` can also live in
+       another directory, the :term:`configuration directory`.  See
+       :ref:`invocation`.
+
+.. |more| image:: more.png
+          :align: middle
+          :alt: more info