collective.recipe.sphinxbuilder 1.1

什么是Sphinx？

Sphinx是Python社区中构建文档的主要工具。参见https://sphinx-doc.cn。

Python等许多其他项目现在都使用它。参见https://docs.pythonlang.cn。

Sphinx使用reStructuredText，可用于编写基于buildout的应用程序。该食谱为您设置一切，因此您可以在buildout中提供漂亮的文档，可以是静态HTML、PDF甚至是epub。

将文档管理得像代码一样，使维护和更改变得容易。

快速开始

要使用该食谱，在buildout配置文件中添加类似以下内容的部分

[buildout]
parts =
    ...
    sphinxbuilder
    ...

[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
source = ${buildout:directory}/docs-source
build = ${buildout:directory}/docs

运行buildout，您将在bin文件夹中获得一些新脚本，名称为

• sphinx-quickstart，用于快速启动Sphinx文档

• sphinxbuilder，脚本将

要快速启动文档项目，就像您通常使用Sphinx一样运行

$ bin/sphinx-quickstart

回答几个问题，并将docs-source作为源文件夹。

要构建您的文档，只需运行sphinx脚本

$ bin/sphinxbuilder

就是这样！

您将在docs/html中获得一个闪亮的Sphinx文档。编写您的文档，进入docs-source。每次源代码更改时，sphinxbuilder都会再次运行脚本。

编写文档的好起点是：https://sphinx-doc.cn/contents.html。

Plone 4

与Plone 4一起使用甚至更容易

[buildout]
parts =
    ...
    sphinxbuilder
    ...

[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
interpreter = ${buildout:directory}/bin/zopepy

遵循快速入门教程，并不要忘记添加带有已安装egg的解释器，以便使用Sphinx访问源代码。

支持选项

该食谱支持以下选项

build（默认：docs）

指定构建文档的根目录。

source（默认：{build-directory}/source）

指定文档的源目录。

outputs（默认：html）

多行值，定义要生成的输出类型。可以是doctest、html、latex、pdf或epub。

script-name（默认：buildout部分名称）

生成的脚本名称

interpreter

使用sphinx-builder时使用的Python解释器的路径。

extra-paths

要插入到sys.path中的额外路径。

products

要扩展旧式Zope Products命名空间的额外产品目录。

示例用法

该食谱可以在没有任何选项的情况下使用。我们将首先创建一个使用该食谱的buildout

>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... """)

让我们运行buildout

>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
Generated script '/sample-buildout/bin/sphinx-quickstart'.
Generated script '/sample-buildout/bin/sphinx-build'.
Generated script '/sample-buildout/bin/sphinx-apidoc'.
Generated script '/sample-buildout/bin/sphinx-autogen'...

我们期待什么？

一个包含Sphinx结构的docs文件夹

>>> docs = join(sample_buildout, 'docs')
>>> ls(docs)
- Makefile
-  make.bat

在bin文件夹中有一个脚本用于构建文档

>>> bin = join(sample_buildout, 'bin')
>>> ls(bin)
- buildout
- sphinx-apidoc
- sphinx-autogen
- sphinx-build
- sphinx-quickstart
- sphinxbuilder

脚本内容是一个简单的shell脚本

>>> script = join(sample_buildout, 'bin', 'sphinxbuilder')
>>> print(open(script).read())
#!/bin/bash
cd ...docs
make html

>>> print('start ' + system(script))
start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees ...src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html
...

如果我们想生成latex，我们需要显式定义它

>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
...     html
...     latex
... """)
>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script...

现在让我们看看我们的脚本

>>> cat(script)
#!/bin/bash
cd ...docs
make html
make latex

最后让我们运行它

>>> print('start ' + system(script))
start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees   .../src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html
...
<BLANKLINE>
Build finished. The HTML pages are in /sample-buildout/docs/html.
...
Build finished; the LaTeX files are in /sample-buildout/docs/latex.
Run `make' in that directory to run these through (pdf)latex...
<BLANKLINE>

如果我们想生成pdf，我们需要显式定义它

>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
...     html
...     latex
...     pdf
... """)
>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script...

现在让我们看看我们的脚本

>>> cat(script)
#!/bin/bash
cd ...docs
make html
make latex
cd /sample-buildout/docs/latex && make all-pdf

由于PDF构建器依赖于可能未安装的库，我们将跳过在测试中运行脚本

如果我们要生成epub，就像pdf一样，我们需要显式定义它

>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
...     html
...     epub
... """)
>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script...

现在让我们看看我们的脚本

>>> cat(script)
#!/bin/bash
cd ...docs
make html
make epub

我们还可以在构建时运行文档中的任何doctests

>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
...     doctest
...     html
... """)
>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script...

现在让我们看看我们的脚本

>>> cat(script)
#!/bin/bash
cd ...docs
make doctest
make html

我们再次跳过运行它们，这次是为了避免递归fork bomb。；)

如果我们想使用extra-paths，我们可以将它们定义为正常路径或Unix通配符（请参阅fnmatch模块）

>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... extra-paths =
...     develop-eggs/
...     eggs/*
... """)
>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
collective.recipe.sphinxbuilder: inserting extra-paths...

贡献者

• Tarek Ziade，原作者

• Rok Garbas

• Sidnei da Silva

• 汉斯-彼得·洛克

• 多门·科扎尔

• 特雷西·西弗

• 莱因乌特·范·里斯，维护者

• 塞巴斯蒂安·多什

变更