merge with 0.5

18 files changed, 366 insertions, 23 deletions

diff --git a/doc/Makefile b/doc/Makefile
index cb5fc645..6da1654b 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -11,12 +11,12 @@ PAPEROPT_letter  = -D latex_paper_size=letter
 ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
                 $(SPHINXOPTS) .
 
-.PHONY: help clean html web htmlhelp latex changes linkcheck
+.PHONY: help clean html pickle htmlhelp qthelp latex changes linkcheck doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
-	@echo "  web       to make files usable by Sphinx.web"
+	@echo "  pickle    to make pickle files"
 	@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 "  changes   to make an overview over all changed/added/deprecated items"
@@ -31,13 +31,15 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in _build/html."
 
+text:
+	mkdir -p _build/text _build/doctrees
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
+	@echo
+	@echo "Build finished."
+
 pickle:
 	mkdir -p _build/pickle _build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
-	@echo
-	@echo "Build finished; now you can run"
-	@echo "  python -m sphinx.web _build/pickle"
-	@echo "to start the server."
 
 htmlhelp:
 	mkdir -p _build/htmlhelp _build/doctrees
@@ -46,6 +48,16 @@ htmlhelp:
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in _build/htmlhelp."
 
+qthelp:
+	mkdir -p _build/qthelp _build/doctrees
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
+	@echo
+	@echo "Build finished; now you can run qcollectiongenerator with the" \
+	      ".qhcp project file in build/qthelp."
+	@echo "# qcollectiongenerator _build/qthelp/Sphinx.qhcp"
+	@echo "To view the help collection:"
+	@echo "# assistant -collectionFile _build/qthelp/Sphinx.qhc"
+
 latex:
 	mkdir -p _build/latex _build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
diff --git a/doc/builders.rst b/doc/builders.rst
index 508ab3c5..dd07a96a 100644
--- a/doc/builders.rst
+++ b/doc/builders.rst
@@ -3,7 +3,7 @@
 Available builders
 ==================
 
-.. module:: sphinx.builder
+.. module:: sphinx.builders
    :synopsis: Available built-in builder classes.
 
 These are the built-in Sphinx builders.  More builders can be added by
@@ -13,6 +13,7 @@ The builder's "name" must be given to the **-b** command-line option of
 :program:`sphinx-build` to select a builder.
 
 
+.. module:: sphinx.builders.html
 .. class:: StandaloneHTMLBuilder
 
    This is the standard HTML builder.  Its output is a directory with HTML
@@ -30,6 +31,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``htmlhelp``. 
 
+.. module:: sphinx.builders.latex
 .. class:: LaTeXBuilder
 
    This builder produces a bunch of LaTeX files in the output directory.  You
@@ -50,6 +52,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``latex``.
 
+.. module:: sphinx.builders.text
 .. class:: TextBuilder
 
    This builder produces a text file for each reST file -- this is almost the
@@ -60,6 +63,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionadded:: 0.4
 
+.. currentmodule:: sphinx.builders.html
 .. class:: SerializingHTMLBuilder
 
    This builder uses a module that implements the Python serialization API
@@ -135,6 +139,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionadded:: 0.5
 
+.. module:: sphinx.builders.changes
 .. class:: ChangesBuilder
 
    This builder produces an HTML overview of all :dir:`versionadded`,
@@ -144,6 +149,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``changes``.
 
+.. module:: sphinx.builders.linkcheck
 .. class:: CheckExternalLinksBuilder
 
    This builder scans all documents for external links, tries to open them with
diff --git a/doc/concepts.rst b/doc/concepts.rst
index ca7aaf7c..23725b10 100644
--- a/doc/concepts.rst
+++ b/doc/concepts.rst
@@ -71,6 +71,9 @@ tables of contents.  The ``toctree`` directive is the central element.
    The second line above will link to the ``strings`` document, but will use the
    title "All about strings" instead of the title of the ``strings`` document.
 
+   You can also add external links, by giving an HTTP URL instead of a document
+   name.
+
    You can use "globbing" in toctree directives, by giving the ``glob`` flag
    option.  All entries are then matched against the list of available
    documents, and matches are inserted into the list alphabetically.  Example::
@@ -85,6 +88,18 @@ tables of contents.  The ``toctree`` directive is the central element.
    This includes first all documents whose names start with ``intro``, then all
    documents in the ``recipe`` folder, then all remaining documents (except the
    one containing the directive, of course.) [#]_
+
+   You can also give a "hidden" option to the directive, like this::
+
+      .. toctree::
+         :hidden:
+
+         doc_1
+         doc_2
+
+   This will still notify Sphinx of the document hierarchy, but not insert links
+   into the document at the location of the directive -- this makes sense if you
+   intend to insert these links yourself, in a different style.
           
    In the end, all documents in the :term:`source directory` (or subdirectories)
    must occur in some ``toctree`` directive; Sphinx will emit a warning if it
@@ -100,6 +115,9 @@ tables of contents.  The ``toctree`` directive is the central element.
    .. versionchanged:: 0.3
       Added "globbing" option.
 
+   .. versionchanged:: 0.6
+      Added "hidden" option and external links.
+
 
 Special names
 -------------
diff --git a/doc/conf.py b/doc/conf.py
index 89247821..709d6f75 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -36,7 +36,7 @@ master_doc = 'contents'
 
 # General substitutions.
 project = 'Sphinx'
-copyright = '2008, Georg Brandl'
+copyright = '2007-2009, Georg Brandl'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
diff --git a/doc/config.rst b/doc/config.rst
index e6af9aae..dd25cf22 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -22,8 +22,8 @@ Important points to note:
 
 * The term "fully-qualified name" refers to a string that names an importable
   Python object inside a module; for example, the FQN
-  ``"sphinx.builder.Builder"`` means the ``Builder`` class in the
-  ``sphinx.builder`` module.
+  ``"sphinx.builders.Builder"`` means the ``Builder`` class in the
+  ``sphinx.builders`` module.
 
 * Remember that document names use ``/`` as the path separator and don't contain
   the file name extension.
@@ -205,6 +205,7 @@ Project information
    * ``en`` -- English
    * ``es`` -- Spanish
    * ``fr`` -- French
+   * ``it`` -- Italian
    * ``nl`` -- Dutch
    * ``pl`` -- Polish
    * ``pt_BR`` -- Brazilian Portuguese
@@ -332,6 +333,15 @@ that use Sphinx' HTMLWriter class.
    If true, *SmartyPants* will be used to convert quotes and dashes to
    typographically correct entities.  Default: ``True``.
 
+.. confval:: html_add_permalinks
+
+   If true, Sphinx will add "permalinks" for each heading and description
+   environment as paragraph signs that become visible when the mouse hovers over
+   them.  Default: ``True``.
+
+   .. versionadded:: 0.6
+      Previously, this was always activated.
+   
 .. confval:: html_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to
@@ -399,6 +409,13 @@ that use Sphinx' HTMLWriter class.
       will only display the titles of matching documents, and no excerpt from
       the matching contents.
 
+.. confval:: html_show_sourcelink
+
+   If true (and :confval:`html_copy_source` is true as well), links to the
+   reST sources will be added to the sidebar.  The default is ``True``.
+
+   .. versionadded:: 0.6
+
 .. confval:: html_use_opensearch
 
    If nonempty, an `OpenSearch <http://opensearch.org>` description file will be
@@ -415,10 +432,18 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 0.4
 
+.. confval:: html_link_suffix
+
+   Suffix for generated links to HTML files.  The default is whatever
+   :confval:`html_file_suffix` is set to; it can be set differently (e.g. to
+   support different web server setups).
+
+   .. versionadded:: 0.6
+   
 .. confval:: html_translator_class
 
    A string with the fully-qualified name of a HTML Translator class, that is, a
-   subclass of Sphinx' :class:`~sphinx.htmlwriter.HTMLTranslator`, that is used
+   subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used
    to translate document trees to HTML.  Default is ``None`` (use the builtin
    translator).
 
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index fcc29e38..00fd2e58 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -13,7 +13,7 @@ the following public API:
 .. method:: Sphinx.add_builder(builder)
 
    Register a new builder.  *builder* must be a class that inherits from
-   :class:`~sphinx.builder.Builder`.
+   :class:`~sphinx.builders.Builder`.
 
 .. method:: Sphinx.add_config_value(name, default, rebuild_env)
 
@@ -86,6 +86,13 @@ the following public API:
    source, *role* the role function (see the `Docutils documentation
    <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ on details).
 
+.. method:: Sphinx.add_generic_role(name, nodeclass)
+
+   Register a Docutils role that does nothing but wrap its contents in the
+   node given by *nodeclass*.
+
+   .. versionadded:: 0.6
+
 .. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None)
 
    This method is a very convenient way to add a new type of information that
@@ -167,6 +174,13 @@ the following public API:
    :confval:`the docs for the config value <html_static_path>`.
 
    .. versionadded:: 0.5
+
+.. method:: Sphinx.add_lexer(alias, lexer)
+
+   Use *lexer*, which must be an instance of a Pygments lexer class, to
+   highlight code blocks with the given language *alias*.
+
+   .. versionadded:: 0.6
    
 .. method:: Sphinx.connect(event, callback)
 
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index 3e5ce3e1..3b2cdb54 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -142,12 +142,30 @@ directive.
 
 
 .. directive:: autofunction
+               autodata
                automethod
                autoattribute
 
    These work exactly like :dir:`autoclass` etc., but do not offer the options
    used for automatic member documentation.
 
+   For module data members and class attributes, documentation can either be put
+   into a special-formatted comment *before* the attribute definition, or in a
+   docstring *after* the definition.  This means that in the following class
+   definition, both attributes can be autodocumented::
+
+      class Foo:
+          """Docstring for class Foo."""
+
+          #: Doc comment for attribute Foo.bar.
+          bar = 1
+
+          baz = 2
+          """Docstring for attribute Foo.baz."""
+
+   .. versionchanged:: 0.6
+      :dir:`autodata` and :dir:`autoattribute` can now extract docstrings.
+
    .. note::
 
       If you document decorated functions or methods, keep in mind that autodoc
diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst
index adc41016..5c671f2d 100644
--- a/doc/ext/builderapi.rst
+++ b/doc/ext/builderapi.rst
@@ -5,7 +5,7 @@ Writing new builders
 
 .. todo:: Expand this.
 
-.. currentmodule:: sphinx.builder
+.. currentmodule:: sphinx.builders
 
 .. class:: Builder
 
@@ -20,7 +20,7 @@ Writing new builders
    .. automethod:: build_update
    .. automethod:: build
 
-   These methods must be overridden in concrete builder classes:
+   These methods can be overridden in concrete builder classes:
 
    .. automethod:: init
    .. automethod:: get_outdated_docs
@@ -28,3 +28,7 @@ Writing new builders
    .. automethod:: prepare_writing
    .. automethod:: write_doc
    .. automethod:: finish
+
+   Useful helpers:
+
+   .. automethod:: init_templates
diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst
index 9de6ba9e..7117f6a9 100644
--- a/doc/ext/doctest.rst
+++ b/doc/ext/doctest.rst
@@ -149,6 +149,14 @@ There are also these config values for customizing the doctest extension:
    A list of directories that will be added to :data:`sys.path` when the doctest
    builder is used.  (Make sure it contains absolute paths.)
 
+.. confval:: doctest_global_setup
+
+   Python code that is treated like it were put in a ``testsetup`` directive for
+   *every* file that is tested, and for every group.  You can use this to
+   e.g. import modules you will always need in your doctests.
+
+   .. versionadded:: 0.6
+   
 .. confval:: doctest_test_doctest_blocks
 
    If this is a nonempty string (the default is ``'default'``), standard reST
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 6a80ad36..7ec787ff 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -6,7 +6,7 @@ Glossary
 .. glossary::
 
    builder
-      A class (inheriting from :class:`~sphinx.builder.Builder`) that takes
+      A class (inheriting from :class:`~sphinx.builders.Builder`) that takes
       parsed documents and performs an action on them.  Normally, builders
       translate the documents to an output format, but it is also possible to
       use the builder builders that e.g. check for broken links in the
diff --git a/doc/intro.rst b/doc/intro.rst
index 47e016b3..7ce9d1fa 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -111,8 +111,12 @@ The :program:`sphinx-build` script has several more options:
    .. versionadded:: 0.5
    
 **-D** *setting=value*
-   Override a configuration value set in the :file:`conf.py` file.  (The value
-   must be a string 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.
diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index 299ab0bc..0bf8343b 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -113,8 +113,35 @@ Includes
       .. literalinclude:: example.py
          :encoding: latin-1
 
+   The directive also supports including only parts of the file.  If it is a
+   Python module, you can select a class, function or method to include using
+   the ``pyobject`` option::
+
+      .. literalinclude:: example.py
+         :pyobject: Timer.start
+
+   This would only include the code lines belonging to the ``start()`` method in
+   the ``Timer`` class within the file.
+
+   Alternately, you can specify exactly which lines to include by giving a
+   ``lines`` option::
+
+      .. literalinclude:: example.py
+         :lines: 1,3,5-10,20-
+
+   This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.
+
+   Another way to control which part of the file is included is to use the
+   ``start-after`` and ``end-before`` options (or only one of them).  If
+   ``start-after`` is given as a string option, only lines that follow the first
+   line containing that string are included.  If ``end-before`` is given as a
+   string option, only lines that precede the first lines containing that string
+   are included.
+
    .. versionadded:: 0.4.3
       The ``encoding`` option.
+   .. versionadded:: 0.6
+      The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options.
 
 
 .. rubric:: Footnotes
diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst
index 892cdc4a..67605c77 100644
--- a/doc/markup/desc.rst
+++ b/doc/markup/desc.rst
@@ -205,6 +205,12 @@ The directives are:
 
    .. versionadded:: 0.4
 
+.. directive:: .. classmethod:: name(signature)
+
+   Like :dir:`method`, but indicates that the method is a class method.
+
+   .. versionadded:: 0.6
+
 
 .. _signatures:
 
diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index 5dbd638e..9f8a01a5 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -224,7 +224,50 @@ to labels:
 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
+---------------------------
+
+.. versionadded:: 0.6
+
+There is also a way to directly link to documents:
+
+.. role:: doc
+
+   Link to the specified document; the document name can be specified in
+   absolute or relative fashion.  For example, if the reference
+   ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link
+   refers to ``sketches/parrot``.  If the reference is ``:doc:`/people``` or
+   ``:doc:`../people```, the link refers to ``people``.
+
+   If no explicit link text is given (like usual: ``:doc:`Monty Python members
+   </people>```), the link caption will be the title of the given document.
+
+
+Referencing downloadable files
+------------------------------
+
+.. versionadded:: 0.6
+
+.. role:: download
+
+   This role lets you link to files within your source tree that are not reST
+   documents that can be viewed, but files that can be downloaded.
+
+   When you use this role, the referenced file is automatically marked for
+   inclusion in the output when building (obviously, for HTML output only).
+   All downloadable files are put into the ``_downloads`` subdirectory of the
+   output directory; duplicate filenames are handled.
+
+   An example::
+
+      See :download:`this example script <../example.py>`.
+
+   The given filename is relative to the directory the current source file is
+   contained in.  The ``../example.py`` file will be copied to the output
+   directory, and a suitable link generated to it.
+
 
 Other semantic markup
 ---------------------
@@ -330,7 +373,7 @@ in a different style:
    curly braces to indicate a "variable" part, as in ``:file:``.
 
    If you don't need the "variable part" indication, use the standard
-   ````code```` instead.   
+   ````code```` instead.
 
 
 The following roles generate external links:
@@ -351,6 +394,7 @@ The following roles generate external links:
 Note that there are no special roles for including hyperlinks as you can use
 the standard reST markup for that purpose.
 
+
 .. _default-substitutions:
 
 Substitutions
diff --git a/doc/markup/para.rst b/doc/markup/para.rst
index c60eb258..b071e46c 100644
--- a/doc/markup/para.rst
+++ b/doc/markup/para.rst
@@ -100,6 +100,27 @@ units as well as normal text:
       .. centered:: LICENSE AGREEMENT
 
 
+.. directive:: hlist
+
+   This directive must contain a bullet list.  It will transform it into a more
+   compact list by either distributing more than one item horizontally, or
+   reducing spacing between items, depending on the builder.
+
+   For builders that support the horizontal distribution, there is a ``columns``
+   option that specifies the number of columns; it defaults to 2.  Example::
+
+      .. hlist::
+         :columns: 3
+
+         * A list of
+         * short items
+         * that should be
+         * displayed
+         * horizontally
+
+   .. versionadded:: 0.6
+
+
 Table-of-contents markup
 ------------------------
 
diff --git a/doc/sphinx-build.1 b/doc/sphinx-build.1
new file mode 100644
index 00000000..16f8bd34
--- /dev/null
+++ b/doc/sphinx-build.1
@@ -0,0 +1,96 @@
+.TH sphinx-build 1 "Jan 2009" "Sphinx 0.6" "User Commands"
+.SH NAME
+sphinx-build \- Sphinx documentation generator tool
+.SH SYNOPSIS
+.B sphinx-build
+[\fIoptions\fR] <\fIsourcedir\fR> <\fIoutdir\fR> [\fIfilenames\fR...]
+.SH DESCRIPTION
+sphinx-build generates documentation from the files in <sourcedir> and places it
+in the <outdir>.
+
+sphinx-build looks for <sourcedir>/conf.py for the configuration settings.
+.B sphinx-quickstart(1)
+may be used to generate template files, including conf.py.
+
+sphinx-build can create documentation in different formats.  A format is
+selected by specifying the builder name on the command line; it defaults to
+HTML.  Builders can also perform other tasks related to documentation
+processing.
+
+By default, everything that is outdated is built.  Output only for selected
+files can be built by specifying individual filenames.
+
+List of available builders:
+.TP
+\fBhtml\fR
+HTML files generation.  This is default builder.
+.TP
+\fBhtmlhelp\fR
+Generates files for CHM generation.
+.TP
+\fBqthelp\fR
+Generates files for Qt help collection generation.
+.TP
+\fBlatex\fR
+Generates a LaTeX version of the documentation.
+.TP
+\fBtext\fR
+Generates a plain-text version of the documentation.
+.TP
+\fBchanges\fR
+Generates HTML files listing changed/added/deprecated items for the
+current version.
+.TP
+\fBlinkcheck\fR
+Checks the integrity of all external links in the documentation.
+.TP
+\fBpickle / json\fR
+Generates serialized HTML files in the selected format.
+
+.SH OPTIONS
+.TP
+\fB-b\fR <builder>
+Builder to use; defaults to html. See the full list of builders above.
+.TP
+\fB-a\fR
+Generates output for all files; without this option only output for
+new and changed files is generated.
+.TP
+\fB-E\fR
+Ignores cached files, forces to re-read all source files from disk.
+.TP
+\fB-c\fR <path>
+Locates the conf.py file in the specified path instead of <sourcedir>.
+.TP
+\fB-C\fR
+Specifies that no conf.py file at all is to be used.  Configuration can
+only be set with the -D option.
+.TP
+\fB-D\fR <setting>=<value>
+Overrides a setting from the configuration file.
+.TP
+\fB-d\fR <path>
+Path to cached files; defaults to <outdir>/.doctrees.
+.TP
+\fB-A\fR <name>=<value>
+Passes a value into the HTML templates (only for html builders).
+.TP
+\fB-N\fR
+Prevents colored output.
+.TP
+\fB-q\fR
+Quiet operation, just prints warnings and errors on stderr.
+.TP
+\fB-Q\fR
+Very quiet operation, doesn't print anything except for errors.
+.TP
+\fB-P\fR
+Runs Pdb on exception.
+.SH "SEE ALSO"
+.BR sphinx-quickstart(1)
+.SH AUTHOR
+Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
+al.
+.PP
+This manual page was initially written by Mikhail Gusarov
+<dottedmag@dottedmag.net>, for the Debian project.
diff --git a/doc/sphinx-quickstart.1 b/doc/sphinx-quickstart.1
new file mode 100644
index 00000000..93b0a4a5
--- /dev/null
+++ b/doc/sphinx-quickstart.1
@@ -0,0 +1,17 @@
+.TH sphinx-quickstart 1 "Jan 2009" "Sphinx 0.6" "User Commands"
+.SH NAME
+sphinx-quickstart \- Sphinx documentation template generator
+.SH SYNOPSIS
+.B sphinx-quickstart
+.SH DESCRIPTION
+sphinx-quickstart is an interactive tool that asks some questions about your
+project and then generates a complete documentation directory and sample
+Makefile to be used with \fBsphinx-build(1)\fR.
+.SH "SEE ALSO"
+.BR sphinx-build(1)
+.SH AUTHOR
+Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
+al.
+.PP
+This manual page was initially written by Mikhail Gusarov
+<dottedmag@dottedmag.net> for the Debian project.
diff --git a/doc/templating.rst b/doc/templating.rst
index 61a8a72b..20c61ce0 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -19,10 +19,10 @@ No.  You have several other options:
   configuration value accordingly.
 
 * You can :ref:`write a custom builder <writing-builders>` that derives from
-  :class:`~sphinx.builder.StandaloneHTMLBuilder` and calls your template engine
+  :class:`~sphinx.builders.StandaloneHTMLBuilder` and calls your template engine
   of choice.
 
-* You can use the :class:`~sphinx.builder.PickleHTMLBuilder` that produces
+* You can use the :class:`~sphinx.builders.PickleHTMLBuilder` that produces
   pickle files with the page contents, and postprocess them using a custom tool,
   or use them in your Web application.
 
@@ -135,6 +135,10 @@ The following blocks exist in the ``layout`` template:
 `sidebarrel`
     The relation links (previous, next document) within the sidebar.
 
+`sidebarsourcelink`
+    The "Show source" link within the sidebar (normally only shown if this is
+    enabled by :confval:`html_show_sourcelink`).
+
 `sidebarsearch`
     The search box within the sidebar.  Override this if you want to place some
     content at the bottom of the sidebar.
@@ -217,8 +221,12 @@ in the future.
 
 .. data:: builder
 
-   The name of the builder (for builtin builders, ``html``, ``htmlhelp``, or
-   ``web``).
+   The name of the builder (e.g. ``html`` or ``htmlhelp``).
+
+.. data:: embedded
+
+   True if the built HTML is supposed to be embedded in some application that
+   handles navigation, e.g. HTML Help or Qt Help.
 
 .. data:: next
 
@@ -235,3 +243,18 @@ in the future.
 .. data:: prev
 
    Like :data:`next`, but for the previous page.
+
+
+In documents that are created from source files (as opposed to
+automatically-generated files like the module index, or documents that already
+are in HTML form), these variables are also available:
+
+.. data:: toc
+
+   The local table of contents for the current page, rendered as HTML bullet
+   lists.
+
+.. data:: toctree
+
+   The global TOC tree containing the current page, rendered as HTML bullet
+   lists.