z3c.recipe.sphinxdoc 1.1.0

简介

此构建工具配置文件辅助从包中的reStructuredText文件生成zope.org网站的文档。它使用Sphinx构建静态HTML文件，这些文件可以作为非常漂亮的网站独立使用。

使用说明

假设你有一个名为 z3c.form 的包。在 z3c.form 的 setup.py 中，建议你向 extras_require 参数添加一个 docs 部分。它看起来可能像这样

extras_require = dict(
    docs = ['Sphinx',
            'z3c.recipe.sphinxdoc']
    )

然后在你的包的 buildout.cfg 文件中添加一个看起来像这样的 docs 部分

[docs]
recipe = z3c.recipe.sphinxdoc
eggs = z3c.form [docs]

确保将其包含在部分中，如下所示

[buildout]
develop = .
parts = docs

现在你可以重新运行 buildout。该配置文件将创建一个在 bin 目录中名为 docs 的可执行脚本。

此脚本将在你的源代码上运行 Sphinx 文档生成工具。默认情况下，它期望在源代码中存在一个 index.rst 文件。在这种情况下，index.rst 必须位于 src/z3c/form/index.rst。此文件可以是标准的 reStructuredText 文件，并可以使用所有的 Sphinx 功能。例如，你的 index.txt 可能看起来像这样

Welcome to z3c.form's documentation!
====================================

Contents:

.. toctree::
   :maxdepth: 2

   README

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

你应该阅读 Sphinx 的文档来了解更多信息。它在这里： https://sphinx-doc.cn/

现在你应该能够运行 docs 脚本

$ ./bin/docs

这将为你生成所有文档并将其放置在部分目录中。然后你可以在 Firefox 中打开它查看

$ firefox parts/docs/z3c.form/build/index.html

附加选项

默认情况下，此配置文件通过覆盖 Sphinx 使用的默认布局模板和 CSS 文件，生成看起来像新 zope 网站（ http://new.zope.org ）的文档。你可以通过在你的构建工具配置中添加选项来修改此行为。

[docs]
recipe = z3c.recipe.sphinxdoc
eggs = z3c.form [docs]
default.css =
layout.html =

[docs]
recipe = z3c.recipe.sphinxdoc
eggs = z3c.form [docs]
default.css = http://my.own.website.com/mystyles/some-theme.css
layout.html = /path/to/layout.html

[docs]
recipe = z3c.recipe.sphinxdoc
eggs = z3c.form [docs]
extensions = sphinx.ext.autodoc sphinx.ext.doctest

[docs]
recipe = z3c.recipe.sphinxdoc
eggs = z3c.form [docs]
extensions = sphinx.ext.autodoc
             sphinx.ext.todo
             sphinx.ext.viewcode
             sphinx.ext.intersphinx
             repoze.sphinx.autointerface
             sphinxcontrib.programoutput
default.css =
layout.html =
extra-conf =
         autodoc_default_flags = ['members', 'show-inheritance',]
         autoclass_content = 'both'
         intersphinx_mapping = {
         'python':  ('https://docs.pythonlang.cn/2.7/', None),
         'boto': ('http://boto.readthedocs.org/en/latest/', None),
         'gunicorn': ('http://docs.gunicorn.org/en/latest/', None),
         'pyquery': ('http://packages.python.org/pyquery/', None) }
         intersphinx_cache_limit = -1
         todo_include_todos = True

         # The suffix of source filenames. Override back to txt.
         source_suffix = '.txt'

         # Choose an entire theme. Note that we disabled layout.html
         # and default.css.
         html_theme = 'classic'

1.1.0 (2017-07-05)

• 添加对 Python 3.4、3.5 和 3.6 以及 PyPy 的支持。

• 删除对 Python 2.6 和 3.3 的支持。

• 将默认源后缀从 .txt 更改为 .rst。您可以使用新的 extra-conf 设置来覆盖此设置。

• 添加在 extra-conf 设置中指定任意配置的能力。这对于配置扩展、覆盖此配方设置的默认值以及配置 Sphinx 主题非常有用。

• 即使在 default.css 设置配置为空值的情况下，也不再强制为 html_style 设置 default.css 的值。这使得可以使用 html_theme 来设置 Sphinx 主题，并且可以正确地使用默认 Sphinx 主题（通过将 default.css 和 layout.html 都设置为空值）。

• 忽略文档工作集中的坏鸡蛋。之前它们会在没有任何解释的情况下引发内部错误。现在，它们记录一个警告，精确地指出坏鸡蛋。修复了 问题 6。

1.0.0 (2013-02-23)

• 增加了 Python 3.3 支持。

• 错误：修复当布局被用户覆盖时的布局目录

0.0.8 (2009-05-01)

• 特性：添加了新的选项 doc-eggs，该选项指定要显式创建文档的 eggs 列表。

• 特性：更改了构建行为，使得每个软件包的文档都在其自己的子目录中构建。

• 特性：添加了新的选项 extensions，它接受一个用空格分隔的 Sphinx 扩展模块列表。这些扩展可以用于构建文档。

0.0.7 (2009-02-15)

• 错误：修复 Python 2.4 支持

• 错误：修复 Windows 上的损坏的 srcDir 路径生成

0.0.6 (2009-01-19)

• 特性：允许您指定自己的 default.css 和 layout.html 文件的 URL 或本地文件路径。

0.0.5 (2008-05-11)

• 首次发布。