Add a paragraph on special names.

doc/concepts.rst

@@ -65,3 +65,35 @@ tables of contents.  The ``toctree`` directive is the central element.
    The "master document" (selected by :confval:`master_doc`) is the "root" of
    the TOC tree hierarchy.  It can be used as the documentation's main page, or
    as a "full table of contents" if you don't give a ``maxdepth`` option.
+
+
+Special names
+-------------
+
+Sphinx reserves some document names for its own use; you should not try to
+create documents with these names -- it will cause problems.
+
+The special document names (and pages generated for them) are:
+
+* ``genindex``, ``modindex``, ``search``
+
+  These are used for the general index, the module index, and the search page,
+  respectively.
+
+  The general index is populated with entries from modules, all index-generating
+  :ref:`description units <desc-units>`, and from :dir:`index` directives.
+
+  The module index contains one entry per :dir:`module` directive.
+
+  The search page contains a form that uses the generated JSON search index and
+  JavaScript to full-text search the generated documents for search words; it
+  should work on every major browser that supports modern JavaScript.
+
+* every name beginning with ``_``
+
+  Though only few such names are currently used by Sphinx, you should not create
+  documents or document-containing directories with such names.  (Using ``_`` as
+  a prefix for a custom template directory is fine.)
+
+``index`` is a special name, too, if the :confval:`html_index` config value is
+nonempty.

doc/config.rst

@@ -166,18 +166,39 @@ that use Sphinx' HTMLWriter class.
 
    Content template for the index page, filename relative to this file.  If this
    is not the empty string, the "index" document will not be created from a
-   reStructuredText file but from this template.
+   reStructuredText file but from the ``index.html`` template.  The template you
+   specify in this value will be included in the ``index.html``, together with
+   a list of tables.
+
+   If you want to completely override the resulting ``index`` document, set this
+   to some nonempty value and override the ``index.html`` template.
 
 .. confval:: html_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to
-   template names.
+   template names.  Example::
+
+      html_sidebars = {
+         'using/windows': 'windowssidebar.html'
+      }
+
+   This will render the template ``windowssidebar.html`` within the sidebar of
+   the given document.
 
 .. confval:: html_additional_pages
 
    Additional templates that should be rendered to HTML pages, must be a
    dictionary that maps document names to template names.
 
+   Example::
+   
+      html_additional_pages = {
+          'download': 'customdownload.html',
+      }
+
+   This will render the template ``customdownload.html`` as the page
+   ``download.html``.
+
 .. confval:: html_use_modindex
 
    If true, add a module index to the HTML documents.   Default is ``True``.

doc/markup/desc.rst

@@ -26,6 +26,8 @@ As you can see, the module-specific markup consists of two directives, the
    submodule, in which case the name should be fully qualified, including the
    package name).
 
+   This directive will also cause an entry in the global module index.
+
    The ``platform`` option, if present, is a comma-separated list of the
    platforms on which the module is available (if it is available on all
    platforms, the option should be omitted).  The keys are short identifiers;
@@ -38,6 +40,7 @@ As you can see, the module-specific markup consists of two directives, the
    The ``deprecated`` option can be given (with no value) to mark a module as
    deprecated; it will be designated as such in various locations then.
 
+
 .. directive:: .. moduleauthor:: name <email>
 
    The ``moduleauthor`` directive, which can appear multiple times, names the
@@ -53,6 +56,8 @@ As you can see, the module-specific markup consists of two directives, the
    in overview files.
 
 
+.. _desc-units:
+
 Description units
 -----------------