自述文件 ¶

作者: David Goodger
联系: goodger@python.org
Date: $Date: 2018-06-10 00:22:09 +0200 (So, 10. Jun 2018) $
Web site: http://docutils.sourceforge.net/
Copyright: This document has been placed in the public domain.

自述文件

The purpose of the Docutils project is to create a set of tools for processing plaintext documentation into useful formats, such as HTML, XML, and LaTeX. Support for the following sources has been implemented:

独立文件。
PEPs (Python Enhancement Proposals).

计划支持以下来源:

Inline documentation from Python modules and packages, extracted with namespace context.
Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
Wikis, with global reference lookups of “wiki links”.
Compound documents, such as multiple chapter files merged into a book.
计划支持以下来源

发布和快照 ¶

While we are trying to follow a “release early & often” policy, features are added frequently. Since the code in the Subversion repository is usually in a bug-free state, we recommend that you use a current snapshot.

To get a snapshot, go to the code page and click the download snapshot button:

Docutils code, documentation, front-end tools, and tests: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
Sandbox (experimental, contributed code): https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/

To keep up to date on the latest developments, download fresh copies of the snapshots regularly or use a working copy of the Subversion repository.

要求 ¶

To run the code, Python must be installed. Docutils is compatible with Python versions 2.6, 2.7, and versions 3.3 to 3.5 (cf. Python聽3 compatibility).

Docutils uses the following packages for enhanced functionality, if they are installed:

The Python Imaging Library, or PIL, is used for some image manipulation operations.
The Pygments syntax highlighter is used for content of code directives and roles.

Python3 compatibility ¶

The Docutils codebase is written for Python聽2 and uses “on-demand” translation for porting to Python聽3.

The setup.py script generates Python聽3 compatible sources in build/ and tests in tests3/ sub-directories during installation with Python聽3.
The scripts in the tools/ sub-directory work with all supported Python versions without conversion.
To convert the sources without installing (e.g. for testing), run python3 setup.py build.
When editing the source, do changes on the Python聽2 versions of the files and re-run the build command.

项目文件和目录 ¶

README.txt: 你正在读它。
COPYING.txt: Public Domain Dedication and copyright details for non-public-domain files (most are PD).
FAQ.txt: Frequently Asked Questions (with answers!).
RELEASE-NOTES.txt: 最近发布的主要变化摘要。
HISTORY.txt: A detailed change log, for the current and all previous project releases.
BUGS.txt: 已知的错误，以及如何报告错误。
THANKS.txt: List of contributors.
setup.py: 安装脚本。请参阅下面的 “Installation” 。
install.py: Quick & dirty installation script. Just run it. For any kind of customization or help though, setup.py must be used.
docutils: 项目源目录，作为Python包安装。
docs: The project documentation directory. Read docs/index.txt for an overview.
docs/user: The project user documentation directory. Contains the following documents, among others:
- docs/user/tools.txt: Docutils前端工具
- docs/user/latex.txt: Docutils LaTeX 作家
- docs/user/rst/quickstart.txt: A ReStructuredText Primer
- docs/user/rst/quickref.html: 快速reStructuredText（仅限HTML）
docs/ref: The project reference directory. docs/ref/rst/restructuredtext.txt is the reStructuredText reference.
licenses: Directory containing copies of license files for non-public-domain files.
tools: Directory for Docutils front-end tools. See docs/user/tools.txt for documentation.
test: Unit tests. Not required to use the software, but very useful if you’re planning to modify it. See Running the Test Suite below.

Generated directories when installing under Python聽3:

build: 转换来源。
test3: 转换测试。

安装 ¶

The first step is to expand the .tgz archive in a temporary directory (not directly in Python’s site-packages). It contains a distutils setup file “setup.py”. OS-specific installation instructions follow.

GNU/Linux, BSDs, Unix, Mac OS X, etc.¶

打开一个外壳。“
Go to the directory created by expanding the archive:
```
cd <archive_directory_path>
```
Install the package (you may need root permissions to complete this step):
```
su
(enter admin password)
python setup.py install
```
If the python executable isn’t on your path, you’ll have to specify the complete path, such as /usr/local/bin/python.

To install for a specific Python version, use this version in the setup call, e.g.
```
python3.1 setup.py install
```
To install for different Python versions, repeat step聽3 for every required version. The last installed version will be used in the shebang line of the rst2*.py wrapper scripts.

Windows ¶

Just double-click install.py. If this doesn’t work, try the following:

Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they’re calling it these days).
Go to the directory created by expanding the archive:
```
cd <archive_directory_path>
```
Install the package:
```
<path_to_python.exe>\python setup.py install
```
To install for a specific python version, specify the Python executable for this version.

To install for different Python versions, repeat step聽3 for every required version.

Optional steps:

running the test suite
converting the documentation

用法 ¶

There are many front-end tools in the unpacked “tools” subdirectory. Installation under Unix places copies in the PATH. You may want to begin with the “rst2html.py” front-end tool. Most tools take up to two arguments, the source path and destination path, with STDIN and STDOUT being the defaults. Use the “–help” option to the front-end tools for details on options and arguments. See Docutils Front-End Tools (docs/user/tools.txt) for full documentation.

The package modules are continually growing and evolving. The docutils.statemachine module is usable independently. It contains extensive inline documentation (in reStructuredText format of course).

欢迎捐款！

转换文档 ¶

After unpacking and installing the Docutils package, the following shell commands will generate HTML for all included documentation:

cd <archive_directory_path>/tools
./buildhtml.py ../

在Windows系统上，键入:

cd <archive_directory_path>\tools
python buildhtml.py ..

The final directory name of the <archive_directory_path> is “docutils” for snapshots. For official releases, the directory may be called “docutils-X.Y.Z”, where “X.Y.Z” is the release version. Alternatively:

cd <archive_directory_path>
tools/buildhtml.py --config=tools/docutils.conf          (Unix)
python tools\buildhtml.py --config=tools\docutils.conf   (Windows)

Some files may generate system messages (warnings and errors). The docs/user/rst/demo.txt file (under the archive directory) contains five intentional errors. (They test the error reporting mechanism!)

运行测试套件 ¶

The test suite is documented in Docutils Testing (docs/dev/testing.txt).

To run the entire test suite, open a shell and use the following commands:

cd <archive_directory_path>/test
./alltests.py

在Windows下，键入:

cd <archive_directory_path>\test
python alltests.py

For testing with Python聽3 use the converted test suite:

cd <archive_directory_path>/test3
python3 alltests.py

You should see a long line of periods, one for each test, and then a summary like this:

Ran 1111 tests in 24.653s

OK
Elapsed time: 26.189 seconds

The number of tests will grow over time, and the times reported will depend on the computer running the tests. The difference between the two times represents the time required to set up the tests (import modules, create data structures, etc.).

If any of the tests fail, please open a bug report or send an email (see Bugs). Please include all relevant output, information about your operating system, Python version, and Docutils version. To see the Docutils version, use one of the rst2* front ends or tools/quicktest.py with the --version option, e.g.:

cd ../tools
./quicktest.py --version

Windows users type these commands:

cd ..\tools
python quicktest.py --version

获得帮助 ¶

如果您对Docutils或reStructuredText有任何疑问或需要帮助，请发送邮件至 Docutils-users 邮件列表。