Commits

ZoomQuiet committed dc9145d

完成教程,开始 build 翻译

Comments (0)

Files changed (5)

 # You can set these variables from the command line.
 SPHINXOPTS   =
 #SPHINXBUILD  = python ../sphinx-build.py
-SPHINXBUILD  = python sphinx-build.py
+#SPHINXBUILD  = python sphinx-build.py
+SPHINXBUILD   = sphinx-build
 PAPER        =
 
 PAPEROPT_a4      = -D latex_paper_size=a4

_templates/index.html

 
   <p>这儿是当前文档的<a href="http://sphinx-users.jp/doc10/">日文翻译</a>,
     感谢Yoshiki Shibukawa.</p>
-  <p>本文是 <a href="http://zoomquiet.org/sphinx_zh/">中文译本</a>
+  <p>本文是 <a href="http://sphinx-doc-zh.readthedocs.org/">中文译本</a>
     由 Zoom.Quiet 私人创建.</p>
 
   <h2>获取 Sphinx</h2>
 import re
 import sphinx
 
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
-              'sphinx.ext.autosummary', 'sphinx.ext.extlinks']
+extensions = ['sphinx.ext.autodoc', 
+    'sphinx.ext.doctest', 
+    'sphinx.ext.todo',
+    'sphinx.ext.autosummary', 
+    #'sphinx.ext.extlinks'
+    ]
 
 master_doc = 'contents'
 templates_path = ['_templates']
                              objname='configuration value',
                              indextemplate='pair: %s; configuration value')
     app.add_description_unit('event', 'event', 'pair: %s; event', parse_event)
+
 .. _invocation:
 
-用 sphinx-build
+使用 sphinx-build
 ==========================
 
-The :program:`sphinx-build` script builds a Sphinx documentation set.  It is
-called like this::
+:program:`sphinx-build` 脚本用以进行 Sphinx 文档的构筑.
+如下使用::
 
      $ sphinx-build [options] sourcedir builddir [filenames]
 
-where *sourcedir* is the :term:`source directory`, and *builddir* is the
-directory in which you want to place the built documentation.  Most of the time,
-you don't need to specify any *filenames*.
+*sourcedir* 指向 :term:`source directory`, 
+而 *builddir* 是指构筑出的文档你想放置的目标路径.
+多数情况,你用不到 *filenames*.
 
-The :program:`sphinx-build` script has several options:
+:program:`sphinx-build` 脚本支持一系列参数:
 
 .. option:: -b buildername
 
-   The most important option: it selects a builder.  The most common builders
-   are:
+   其中最重要的是: 指明使用什么构筑器.  
+   常见的有:
 
    **html**
-      Build HTML pages.  This is the default builder.
+      构筑为 HTML 页面,这是默认构筑器.
 
    **dirhtml**
-      Build HTML pages, but with a single directory per document.  Makes for
-      prettier URLs (no ``.html``) if served from a webserver.
+      构筑为 HTML 页面,不过输出到单一目录中,并为web发布制作为美化URL(不是 ``.html``).
 
    **singlehtml**
-      Build a single HTML with the whole content.
+      构筑为包含所有内容的单页HTML .
 
    **htmlhelp**, **qthelp**, **devhelp**, **epub**
-      Build HTML files with additional information for building a documentation
-      collection in one of these formats.
+      构筑为HTML 文件,并配合附加信息,打包成以上格式中指定的一种.
 
    **latex**
-      Build LaTeX sources that can be compiled to a PDF document using
-      :program:`pdflatex`.
+      构筑为 LaTeX 源码,以便使用 :program:`pdflatex` 编译成 PDF 文档.
 
    **man**
-      Build manual pages in groff format for UNIX systems.
+      构筑为手册页面,使用UNIX系统中的 groff 格式.
 
    **text**
-      Build plain text files.
+      构筑为纯文本文件.
 
    **gettext**
-      Build gettext-style message catalogs (``.pot`` files).
+      构筑为 ``gettext-style`` 消息索引 (``.pot`` 文档).
 
    **doctest**
-      Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
-      extension is enabled.
+      如果 :mod:`~sphinx.ext.doctest` 扩展已激活,执行所有文档中的 doctests .
 
    **linkcheck**
-      Check the integrity of all external links.
+      检查所有外部链接的完整性
 
-   See :ref:`builders` for a list of all builders shipped with Sphinx.
-   Extensions can add their own builders.
+   参考 :ref:`builders` 列出所有Sphinx 内置的构筑器.
+   扩展可以拥有自个儿的构筑器.
 
 .. option:: -a
 
 .. describe:: SPHINXOPTS
 
    Additional options for :program:`sphinx-build`.
+
+
 |more| 参考 :ref:`build-config` 了解所有配置项.
 
 
-自动化 Autodoc
---------------
+自文档(Autodoc)
+----------------------------
 
 
-When documenting Python code, it is common to put a lot of documentation in the
-source files, in documentation strings.  Sphinx supports the inclusion of
-docstrings from your modules with an :dfn:`extension` (an extension is a Python
-module that provides additional features for Sphinx projects) called "autodoc".
+当想对 Python 代码进行文档化时,
+通常的作法是将大量内容直接填入源代码各个文档字串位置.
+Sphinx 支持直接从你的模块中摄取这类文档,
+通过"自文档(autodoc)" :dfn:`extension` (扩展,是个标准的Python 模块,可以为Sphinx 工程提供附加能力;-).
 
-In order to use autodoc, you need to activate it in :file:`conf.py` by putting
-the string ``'sphinx.ext.autodoc'`` into the list assigned to the
-:confval:`extensions` config value.  Then, you have a few additional directives
-at your disposal.
+要使用 自文档(autodoc)扩展,
+首先要在 :file:`conf.py` 中激活,
+通过在 :confval:`extensions`配置项列表中包含  ``'sphinx.ext.autodoc'``  .
+这样,你就有几个附加指令可用了.
 
-For example, to document the function ``io.open()``, reading its
-signature and docstring from the source file, you'd write this::
+例如,对函式 ``io.open()`` 进行文档化,你想从源代码中提取其特征和文档字串,可以写::
 
    .. autofunction:: io.open
 
-You can also document whole classes or even modules automatically, using member
-options for the auto directives, like ::
+当然,也可以对整个类或是模块进行自动摄取,
+使用同类的自文档指令::
 
    .. automodule:: io
       :members:
 
-autodoc needs to import your modules in order to extract the docstrings.
-Therefore, you must add the appropriate path to :py:data:`sys.path` in your
-:file:`conf.py`.
 
-|more| See :mod:`sphinx.ext.autodoc` for the complete description of the
-features of autodoc.
+自文档(autodoc)需要导入你的模块来加载文档字串,
+所以,你得在配置文件 :file:`conf.py` 的 :py:data:`sys.path` 字段里,追加目标模块所在路径.
 
+|more| 参考 :mod:`sphinx.ext.autodoc` 获得完整的使用说明.
 
-More topics to be covered
--------------------------
 
-- Other extensions (math, intersphinx, viewcode, doctest)
-- Static files
-- Selecting a theme
-- Templating
-- Using extensions
-- Writing extensions
+更多相关主题 More topics to be covered
+--------------------------------------------------
+
+- 其它扩展 (math, intersphinx, viewcode, doctest)
+- 静态文件 Static files
+- 选择样式 Selecting a theme
+- 模板 Templating
+- 使用扩展 Using extensions
+- 编写扩展 Writing extensions
 
 
 .. include:: tutorial-footnote.rst