|
Size: 5348
Comment:
|
Size: 602
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| SEE:: 1. [[DocumentUsageSphinx|用Sphinx写文档]] 1. [[UsageSphinxExPdf|用Sphinx生成中文PDF]] |
|
| Line 2: | Line 5: |
| .. _contents: | |
| Line 3: | Line 7: |
| 简介 ============ |
Sphinx 文档内容 ============================= |
| Line 6: | Line 10: |
| 本文档介绍的是文档编制软件 Sphinx 。该工具可以将一系列 reStructuredText 源 文本转换成各种不同的输出格式，并自动制作交叉引用（cross-references)、索引 等。也就是说，如果某目录中有一系列的 reST 格式文档（可能子目录中也有）， Sphinx 可以制作一份组织得非常完美的 HTML 文件（在其它目录中），便于浏览 和查找。但是从一组源文件，它也可以制作一份 LaTex 文件，以便你将其转换为PDF 格式的文档。 The focus is on hand-written documentation, rather than auto-generated API docs. Though there is limited support for that kind of docs as well (which is intended to be freely mixed with hand-written content), if you need pure API docs have a look at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST. |
* `简介 <SphinxIntroduction>`_ * `概念 <SpinxConcepts>`_ * `reST入门 <SphinxreST>`_ * `标记（索引) <SphinxMarkupIndex>`_ * `编译器 <SphinxBuilders>`_ * `配置 <SphinxConfig>`_ * `模板 <SphinxTemplating>`_ * `扩展 <SphinxExtensions>`_ * glossary * changes * examples |
| Line 19: | Line 24: |
| Conversion from other systems ----------------------------- |
索引和列表 ================== |
| Line 22: | Line 27: |
| This section is intended to collect helpful hints for those wanting to migrate to reStructuredText/Sphinx from other documentation systems. * Gerard Flanagan has written a script to convert pure HTML to reST; it can be found at `Launchpad <http://bazaar.launchpad.net/~grflanagan/python-rattlebag/trunk/annotate/head:/src/html2rest.py>`_. * For converting the old Python docs to Sphinx, a converter was written which can be found at `the Python SVN repository <http://svn.python.org/projects/doctools/converter>`_. It contains generic code to convert Python-doc-style LaTeX markup to Sphinx reST. Prerequisites ------------- Sphinx needs at least **Python 2.4** to run. If you like to have source code highlighting support, you must also install the Pygments_ library, which you can do via setuptools' easy_install. Sphinx should work with docutils version 0.4 or some (not broken) SVN trunk snapshot. .. _reStructuredText: http://docutils.sf.net/rst.html .. _Pygments: http://pygments.org Setting up the documentation sources ------------------------------------ The root directory of a documentation collection is called the :dfn:`source directory`. Normally, this directory also contains the Sphinx configuration file :file:`conf.py`, but that file can also live in another directory, the :dfn:`configuration directory`. .. versionadded:: 0.3 Support for a different configuration directory. Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a source directory and creates a default :file:`conf.py` from a few questions it asks you. Just run :: $ sphinx-quickstart and answer the questions. Running a build --------------- A build is started with the :program:`sphinx-build` script. It is called like this:: $ sphinx-build -b latex sourcedir builddir where *sourcedir* is the :term:`source directory`, and *builddir* is the directory in which you want to place the built documentation (it must be an existing directory). The :option:`-b` option selects a builder; in this example Sphinx will build LaTeX files. The :program:`sphinx-build` script has several more options: **-a** If given, always write all output files. The default is to only write output files for new and changed source files. (This may not apply to all builders.) **-E** Don't use a saved :term:`environment` (the structure caching all cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run. **-d** *path* Since Sphinx has to read and parse all source files before it can write an output file, the parsed source files are cached as "doctree pickles". Normally, these files are put in a directory called :file:`.doctrees` under the build directory; with this option you can select a different cache directory (the doctrees can be shared between all builders). **-c** *path* Don't look for the :file:`conf.py` in the source directory, but use the given configuration directory instead. Note that various other files and paths given by configuration values are expected to be relative to the configuration directory, so they will have to be present at this location too. .. versionadded:: 0.3 **-C** Don't look for a configuration file; only take options via the ``-D`` option. .. versionadded:: 0.5 **-D** *setting=value* Override a configuration value set in the :file:`conf.py` file. (The value must be a string value.) **-A** *name=value* Make the *name* assigned to *value* in the HTML templates. **-N** Do not do colored output. (On Windows, colored output is disabled in any case.) **-q** Do not output anything on standard output, only write warnings and errors to standard error. **-Q** Do not output anything on standard output, also suppress warnings. Only errors are written to standard error. **-P** (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an unhandled exception occurs while building. You can also give one or more filenames on the command line after the source and build directories. Sphinx will then try to build only these output files (and their dependencies). |
* `genindex`_ * `modindex`_ * `search`_ * `glossary`_ |
SEE::
.. _contents: Sphinx 文档内容 ============================= * `简介 <SphinxIntroduction>`_ * `概念 <SpinxConcepts>`_ * `reST入门 <SphinxreST>`_ * `标记（索引) <SphinxMarkupIndex>`_ * `编译器 <SphinxBuilders>`_ * `配置 <SphinxConfig>`_ * `模板 <SphinxTemplating>`_ * `扩展 <SphinxExtensions>`_ * glossary * changes * examples 索引和列表 ================== * `genindex`_ * `modindex`_ * `search`_ * `glossary`_