SpinxConcepts

Sphinx 概念
============

:原文地址: `<http://sphinx.pocoo.org/concepts.html>`_

:翻译人员: `CliffPeng`_

:翻译日期: 2009年01月30日

.. _concepts:


文档名称（Document names）
--------------------------------------------

由于 reST 源文件可以有多种不同的扩展名（一些人喜欢 ``.txt`` ，一些人喜欢
``.rst`` ——可以通过 `source_suffix <SphinxSourceSuffix>`_ 来配置扩展名），
而且不同的操作系统使用不同的路径分隔符，Sphinx 对它们进行了抽象处理：
所有的 "文档名称" 与 `源目录 <SphinxSourceDirectory>`_ 相关联，扩展名被
截去，同时路径分割符被转换成斜杠。所有的引用“文档”的变量、参数等等均
期望获取这样的“文档名称”。


TOC 树
------------

由于 reST 缺乏将不同文档相互连接或者将文档分割到多个输出文件的机制，
Sphinx 使用了一个自定义的指令（directive）在组成文档的单个文件之间添加
关系，就像内容列表一样。指令 ``toctree`` 就是其核心元素。

指令：toctree
   通过使用该指令主体部分（其路径相对于该指令出现的文档）给出文档的单个
   TOC （包括 "sub-TOC 树")， 该指令在当前位置插入一棵 "TOC 树" 。可给出
   数字的 ``maxdepth`` 选项来制定树的深度；缺省情况将包含所有的层次。[1]_

   考虑一下面的实例（从Python 文档的类库参考索引中节选而来）::

      .. toctree::
         :maxdepth: 2

         intro
         strings
         datatypes
         numeric
         (many more documents listed here)

   该例子完成了两项任务:

 * 从各个文档中抽取了内容列表并插入当前文档，最大深度为二，也就是说只嵌套
   一层标题。同时这些文档中的  ``toctree`` 也计算在内。

 * Sphinx 知道了 ``intro`` , ``string`` 等文档之间的相对顺序，并掌握它们是目前显示
   类库索引文档的子文档。根据该信息，它生成了 "next chapter", "previous chapter" 和 "parent chapter" 链接。
     
   Document titles in the :dir:`toctree` will be automatically read from the
   title of the referenced document. If that isn't what you want, you can give
   the specify an explicit title and target using a similar syntax to reST
   hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
   looks like::
   
       .. toctree::
          
          intro
          All about strings <strings>
          datatypes
          
   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 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::

      .. toctree::
         :glob:

         intro*
         recipe/*
         *

   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.) [#]_
          
   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
   finds a file that is not included, because that means that this file will not
   be reachable through standard navigation.  Use :confval:`unused_documents` to
   explicitly exclude documents from building, and :confval:`exclude_dirs` to
   exclude whole directories.

   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.

   .. versionchanged:: 0.3
      Added "globbing" 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.)


.. rubric:: Footnotes

.. [#] The ``maxdepth`` option does not apply to the LaTeX writer, where the
       whole table of contents will always be presented at the begin of the
       document, and its depth is controlled by the ``tocdepth`` counter, which
       you can reset in your :confval:`latex_preamble` config value using
       e.g. ``\setcounter{tocdepth}{2}``.

.. [#] A note on available globbing syntax: you can use the standard shell
       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
       these all don't match slashes.  A double star ``**`` can be used to match
       any sequence of characters *including* slashes.