Write a bit more of the tutorial.

4 files changed, 148 insertions, 37 deletions

diff --git a/doc/config.rst b/doc/config.rst
index fae85fc4..611b7476 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -1,5 +1,7 @@
 .. highlightlang:: python
 
+.. _build-config:
+
 The build configuration file
 ============================
 
diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index 4f98f021..298c999c 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -49,47 +49,47 @@ more versatile:
 Cross-referencing arbitrary locations
 -------------------------------------
 
-.. index:: pair: ref; role
+.. role:: ref
 
-To support cross-referencing to arbitrary locations in any document, the
-standard reST labels are used.  For this to work label names must be unique
-throughout the entire documentation.  There are two ways in which you can refer
-to labels:
+   To support cross-referencing to arbitrary locations in any document, the
+   standard reST labels are used.  For this to work label names must be unique
+   throughout the entire documentation.  There are two ways in which you can
+   refer to labels:
 
-* If you place a label directly before a section title, you can reference to it
-  with ``:ref:`label-name```.  Example::
+   * If you place a label directly before a section title, you can reference to
+     it with ``:ref:`label-name```.  Example::
 
-     .. _my-reference-label:
+        .. _my-reference-label:
 
-     Section to cross-reference
-     --------------------------
+        Section to cross-reference
+        --------------------------
 
-     This is the text of the section.
+        This is the text of the section.
 
-     It refers to the section itself, see :ref:`my-reference-label`.
+        It refers to the section itself, see :ref:`my-reference-label`.
 
-  The ``:ref:`` role would then generate a link to the section, with the link
-  title being "Section to cross-reference".  This works just as well when
-  section and reference are in different source files.
+     The ``:ref:`` role would then generate a link to the section, with the link
+     title being "Section to cross-reference".  This works just as well when
+     section and reference are in different source files.
 
-  Automatic labels also work with figures: given ::
+     Automatic labels also work with figures: given ::
 
-     .. _my-figure:
+        .. _my-figure:
 
-     .. figure:: whatever
+        .. figure:: whatever
 
-        Figure caption
+           Figure caption
 
-  a reference ``:ref:`my-figure``` would insert a reference to the figure with
-  link text "Figure caption".
+     a reference ``:ref:`my-figure``` would insert a reference to the figure
+     with link text "Figure caption".
 
-* Labels that aren't placed before a section title can still be referenced to,
-  but you must give the link an explicit title, using this syntax: ``:ref:`Link
-  title <label-name>```.
+   * Labels that aren't placed before a section title can still be referenced
+     to, but you must give the link an explicit title, using this syntax:
+     ``:ref:`Link title <label-name>```.
 
-Using :role:`ref` is advised over standard reStructuredText links to sections
-(like ```Section title`_``) because it works across files, when section headings
-are changed, and for all builders that support cross-references.
+   Using :role:`ref` is advised over standard reStructuredText links to sections
+   (like ```Section title`_``) because it works across files, when section
+   headings are changed, and for all builders that support cross-references.
 
 
 Cross-referencing documents
diff --git a/doc/rest.rst b/doc/rest.rst
index 146b627d..1194903a 100644
--- a/doc/rest.rst
+++ b/doc/rest.rst
@@ -1,5 +1,7 @@
 .. highlightlang:: rest
 
+.. _rst-primer:
+
 reStructuredText Primer
 =======================
 
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index d3e40dee..4ab8c06b 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -27,8 +27,8 @@ configuration values from a few questions it asks you.  Just run ::
 and answer its questions.  (Be sure to say yes to the "autodoc" extension.)
 
 
-Adding some content
--------------------
+Defining document structure
+---------------------------
 
 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
@@ -77,11 +77,27 @@ 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.)
+You can now create the files you listed in the toctree and add content, 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.)
+
+
+Adding content
+--------------
+
+In Sphinx source files, you can use most features of standard reStructuredText.
+There are also several features added by Sphinx.  For example, you can add
+cross-file references in a portable way (which works for all output types) using
+the :role:`ref` role.  Here is a small example of how a source file could look
+like::
+
+   XXX
+
+|more| See :ref:`rst-primer` for a more in-depth introduction to
+reStructuredText and :ref:`sphinxmarkup` for a full list of markup added by
+Sphinx.
 
 
 Running the build
@@ -112,15 +128,106 @@ an argument to see which targets are available.
 Documenting objects
 -------------------
 
+One of Sphinx' main objectives is easy documentation of :dfn:`objects` (in a
+very general sense) in any :dfn:`domain`.  A domain is a collection of object
+types that belong together, complete with markup to create and reference
+descriptions of these objects.
+
+The most prominent domain is the Python domain.  To e.g. document the Python
+built-in function ``enumerate()``, you would add this to one of your source
+files::
+
+   .. py:function:: enumerate(sequence[, start=0])
+
+      Return an iterator that yields tuples of an index and an item of the
+      *sequence*. (And so on.)
+
+This is rendered like this:
+
+.. py:function:: enumerate(sequence[, start=0])
+
+   Return an iterator that yields tuples of an index and an item of the
+   *sequence*. (And so on.)
+
+The argument of the directive is the :dfn:`signature` of the object you
+describe, the content is the documentation for it.  Multiple signatures can be
+given, each in its own line.
+
+The Python domain also happens to be the default domain, so you don't need to
+prefix the markup with the domain name::
+
+   .. function:: enumerate(sequence[, start=0])
+
+      ...
+
+does the same job if you keep the default setting for the default domain.
+
+There are several more directives for documenting other types of Python objects,
+for example :dir:`py:class` or :dir:`py:method`.  There is also a
+cross-referencing :dfn:`role` for each of these object types.  This markup will
+create a link to the documentation of ``enumerate()``::
+
+   The :py:func:`enumerate` function can be used for ...
+
+And here is the proof: A link to :func:`enumerate`.
+
+Again, the ``py:`` can be left out if the Python domain is the default one.  It
+doesn't matter which file contains the actual documentation for ``enumerate()``;
+Sphinx will find it and create a link to it.
+
+Each domain will have special rules for how the signatures can look like, and
+make the formatted output look pretty, or add specific features like links to
+parameter types, e.g. in the C/C++ domains.
+
+|more| See :ref:`domains` for all the available domains and their
+directives/roles.
+
+
+Basic configuration
+-------------------
+
+Earlier we mentioned that the :file:`conf.py` file controls how Sphinx processes
+your documents.  In that file, which is executed as a Python source file, you
+assign configuration values.  For advanced users: since it is executed by
+Sphinx, you can do non-trivial tasks in it, like extending :data:`sys.path` or
+importing a module to find out the version your are documenting.
+
+The config values that you probably want to change are already put into the
+:file:`conf.py` by :program:`sphinx-quickstart` and initially commented out
+(with standard Python syntax: a ``#`` comments the rest of the line).  To change
+the default value, remove the hash sign and modify the value.  To customize a
+config value that is not automatically added by :program:`sphinx-quickstart`,
+just add an additional assignment.
+
+Keep in mind that the file uses Python syntax for strings, numbers, lists and so
+on.  The file is saved in UTF-8 by default, as indicated by the encoding
+declaration in the first line.  If you use non-ASCII characters in any string
+value, you need to use Python Unicode strings (like ``project = u'Exposé'``).
+
+|more| See :ref:`build-config` for documentation of all available config values.
+
+
+Autodoc
+-------
+
+When documenting Python code, it is common to put a lot of documentation in the
+source files, in documentation strings.  Sphinx supports the inclusion of
+docstrings from your modules with an :dfn:`extension` (an extension is a Python
+module that provides additional features for Sphinx projects) called "autodoc".
+
+In order to use autodoc, you need to activate it in :file:`conf.py` by putting
+the string ``'sphinx.ext.autodoc'`` into the list assigned to the
+:confval:`extensions` config value.  Then, you have a few additional directives
+at your disposal.
 
+|more| See :mod:`sphinx.ext.autodoc` for the complete description of the
+features of autodoc.
 
 
 Topics to be covered
 --------------------
 
-- Autodoc
-- Other Domains
-- Basic configuration
+- Other extensions (math, intersphinx, viewcode, doctest)
 - Static files
 - Selecting a theme
 - Templating