Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!

Close
Python 文档 README
~~~~~~~~~~~~~~~~~~~~~~~~~~~

该文档包含用于构建 Python 文档的 reStructuredText (reST). 你不需要自己建造它们,
预编译版本在 http://docs.python.org/download/.

关于怎么编写 Python 文档的文档在本文档的 "编写 Python 的文档" 部分,
它包含风格和标记的信息. 其中还有一章指出了 reST 文档与 LaTeX 文档的异同.


建造文档
==========================

你需要安装 Python 2.4 或更高版本; 用于建造该文档的工具包是用 Python 写的.
它叫做 *Sphinx*, 它不包含在 Python 树上, 而需要单独维护.
还需要 docutils, 它提供 Sphinx 使用的基本标记, Jinja,
它是一个模板引擎, 还有可选的 Pygments, 它是一个代码高亮器.

使用 make
----------

幸运的是, 已经准备了一个 Makefile, 以便在 Unix 上, 只要你安装了 Python
和 Subversion, 你就运行 ::

   cd Doc
   make html

来 check out :file:`tools/` 子目录下的必要工具,
以及建造 HTML 格式输出文件. 要查看生成的 HTML, 在运行 "make"
之后, 用你最爱的浏览器打开 :file:`build/html/index.html`.
(你可以使用 :ref:`FireFox <http://www.mozilla.org/en-US/firefox/new/>`
(:ref:`火狐 <http://firefox.com.cn/download/>`)

可用的 make targets 有:

 * "html", 这将建造独立的 HTML 文件供离线阅读.
 * 这将建造 HTML 文件以及一个 HTML Help 项目文件,
   可以用它们编译成一个单独的 HTML (.chm) 文件 --
   在 Microsoft Windows 下很流行, 在每个平台上都非常方便.

   要创建 CHM 文件, 你需要用 Microsoft Help Workshop
   打开生成的项目 (.hhp) 文件.

 * "latex", 这将建造 LaTeX 源文件, 可以作为 "pdflatex" 的输入来产生 PDF
   文档.

 * "text", 这将为每个源文件生成一个纯文本文件.

 * "linkcheck", 这将检查所有的外部引用是否坏了, 
   重定向了 或者 存在异常, 并且输出这些信息到
   stdout 以及 一个纯文本 (.txt) 文件.

 * 这将建造一个覆盖在当前版本下所有 版本增加/版本改变/失效 的条目.
   这意味着这可以作为 "最近更新" 文档作者的一个帮手.

 * 这将建造一个覆盖标准库模块和 C API 的概要.

 * "pydoc-topics", 这将建造一个 Python 模块, 它包含一个为字典, 键为
    :file:`tools/sphinxext/pyspecific.py` 中定义的标签,
    内容是其纯文本文档 -- pydoc 需要这些来显示主题和关键自帮助.

"make update" 使用 Subversion 更新的 :file:`tools/` 中的文件.

没有 make
------------

你需要安装 Sphinx 包, 可以通过 svn co ::

   svn co http://svn.python.org/projects/external/Sphinx-0.6.5/sphinx tools/sphinx

也可以从 PyPI 里安装它.

然后, 你需要安装 Docutils, 可以通过 svn co ::

   svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils

也可以从 http://docutils.sf.net/ 安装它.

你还需要 Jinja2, 可以通过 svn co ::

   svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2

也可以从 PyPI 里安装它.

你也可以安装 Pygments (可选), 可以通过 svn co ::

   svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments

也可以从 http://pypi.python.org/pypi/Pygments 安装它.


Then, make an output directory, e.g. under `build/`, and run
然后, 指定一个输出文件夹, 如 `build/`, 并运行 ::

   python tools/sphinx-build.py -b<builder> . build/<outputdirectory>

在这里 `<builder>` 为 html, text, latex, htmlhelp 中之一
(解释见上文的 make targets).

贡献
============

内容中的 bug 应当提交到 Python bug tracker, http://bugs.python.org.
翻译中的 bug 应当提交到 OBP bug tracker,
http://code.google.com/p/openbookproject/issues/entry.

工具包中的 bug 应当提交到 Sphinx bug tracker,
http://www.bitbucket.org/birkenfeld/sphinx/issues/.

你也可以发邮件给 Python 文档小组, docs@python.org, 我们会尽快地给你答复.
(Python 文档(简体中文) 小组, python-doc-translation@googlegroups.com)

如果你想为 Documentation 小组提供帮助, 随时欢迎. 发封邮件到
docs@python.org 就行了.


版权声明
================

Python 的源代码拥有版权, 但你可以在不改变, 删除以下的版权声明的情况下,
自由地使用和复制它:

----------------------------------------------------------------------
Copyright (c) 2000-2011 Python Software Foundation.
All rights reserved.

Copyright (c) 2000 BeOpen.com.
All rights reserved.

Copyright (c) 1995-2000 Corporation for National Research Initiatives.
All rights reserved.

Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
All rights reserved.

参见 "license.rst" 文件获得使用和重新发布这个文件的信息,
以及 *所有担保的免责声明*.
----------------------------------------------------------------------

Recent activity

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.