Anonymous committed b845257

Add a paragraph on special names.

Comments (0)

Files changed (3)

    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
    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``.


    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;
    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
    in overview files.
+.. _desc-units:
 Description units