{{{#!rst Sphinx 概念 ============ :原文地址: ``_ :翻译人员: `CliffPeng`_ :翻译日期: 2009年01月30日 .. _concepts: 文档名称（Document names） -------------------------------------------- 由于 reST 源文件可以有多种不同的扩展名（一些人喜欢 ``.txt`` ，一些人喜欢 ``.rst`` ——可以通过 `source_suffix `_ 来配置扩展名）， 而且不同的操作系统使用不同的路径分隔符，Sphinx 对它们进行了抽象处理： 所有的 "文档名称" 与 `源目录 `_ 相关联，扩展名被 截去，同时路径分割符被转换成斜杠。所有的引用“文档”的变量、参数等等均 期望获取这样的“文档名称”。 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）"等链接。 目录 `toctree `_ 中的文档标题将会自动从所引用文档的标题中读 取。如果该标题并非你想要的，你可以使用和 reST 超链接类似的语法（或 Sphinx 的 `交叉引用语法 `_ ）制定明确的标题和目标。看起来会 是下面这样:: .. toctree:: intro All about strings datatypes 上面的第二行将会链接到 ``strings`` 文档，但是会使用标题 "All about strings" ，而 不是文档 ``strings`` 的标题。 通过指定 ``glob`` 选项，你可以在 toctree 指令中使用 "globbing" 。这么一来，所有的 条目将会与列出的可用文档清单进行匹配，然后已匹配的将会按照字母顺序插入清单当中。例如:: .. toctree:: :glob: intro* recipe/* * 该例将首先包含所有名字以 ``intro`` 开头的文档，然后是所有 ``recipe`` 文件夹中的 文档，然后是剩下的其他文档（当然，除了包含该指令的文档）[#]_ 最后要说的是，在 `源目录 `_ （或其子目录）中的所有文档必 须在某个 ``toctree`` 指令中出现；如果发现某个文件从未出现，Sphinx 将会发出一条警告， 因为这就意味着该文件无法通过正常的导航进行访问。通过配置变量 *unused_documents* 可明确地 排除不需编译的文档，使用配置变量 *exclude_dirs* 则排除整个目录。 "主文档（master document）" (通过配置变量 *master_doc* 设定）是整个 TOC 树体系的 “根”。它可用作文档的主页，或者作为“完整的内容列表”（如果没有设定 ``maxdepth`` 选项）。 自 0.3 版开始增加 "globbing" 选项。 特别的名称 ------------- Sphinx 保留了一些文档名称自用；你不应该试图使用这些名字创建文档——这将导致问题。 这些特别的文档（及自其创建的页面）名称包括: * ``genindex``, ``modindex``, ``search`` 它们分别用于总索引、模块索引和搜索页面。 总索引中的条目来自所有模块中用于索引生成的 `描述单元(descirption units) `_ , 以及 `index（索引）指令 `_ 。 模块索引对每个 `module 指令 `_ 都包含一个条目。 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 配置变量 *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. }}}