sphinxcontrib-paverutils 1.17.0

基本用法

要使用此模块，请将其导入到您的pavement.py文件中，使用from sphinxcontrib import paverutils，然后使用任务帮助中描述的选项定义“html”和/或“pdf”输出的Bundles选项。

例如

import paver
import paver.misctasks
from paver.path import path
from paver.easy import *
import paver.setuputils
paver.setuputils.install_distutils_tasks()
try:
    from sphinxcontrib import paverutils
except:
    import warnings
    warnings.warn('sphinxcontrib.paverutils was not found, you will not be able to produce documentation')

options(
    setup=Bunch(
        name = 'MyProject',
        version = '1.0',

        # ... more options here ...
        ),

    # Defaults for sphinxcontrib.paverutils
    sphinx = Bunch(
        docroot='.',
        sourcedir='docsource',
        builder='html',
    ),

    # One configuration to build HTML for the package
    html=Bunch(
        builddir='docs',
        confdir='sphinx/pkg',
    ),

    # Another configuration with different templates
    # to build HTML to upload to the website
    website=Bunch(
        builddir = 'web',
        confdir='sphinx/web',
    ),

    # We also want a PDF file for the website,
    # so the instructions are included in the web
    # configuration directory.
    pdf=Bunch(
        builddir='web',
        builder='latex',
        confdir='sphinx/web',
    ),

)

任务

在您将sphinxcontrib.paverutils导入到您的pavement.py文件之后，Paver将显示两个额外的任务。html取代了paver.doctools中定义的任务，并可用于构建HTML输出。pdf使用LaTeX构建器和如TeXLive的外部工具集来创建PDF手册。

配置参数

docroot

Sphinx将工作的根目录。

默认值: docs

builddir

将生成的文件放置在docroot下的目录。

默认： build

sourcedir

docroot下的源文件目录

默认： ""（空字符串）

doctrees

缓存的doctrees位置

默认： $builddir/doctrees

confdir

sphinx conf.py的位置

默认： $sourcedir

outdir

生成输出文件的位置

默认： $builddir/$builder

builder

要使用的sphinx构建器的名称

默认： html

template_args

要作为键值对传递给HTML构建器的值字典

默认： {}

高级用法

您也可以通过直接调用 run_sphinx() 来开发自己的任务

@task
@needs(['cog'])
@cmdopts([
    ('in-file=', 'b', 'Blog input filename'),
    ('out-file=', 'B', 'Blog output filename'),
])
def blog(options):
    """Generate the blog post version of the HTML for the current module.
    """
    # Generate html from sphinx
    paverutils.run_sphinx(options, 'blog')

    blog_file = path(options.blog.outdir) / options.blog.out_file
    dry("Write blog post body to %s" % blog_file,
        gen_blog_post,
        outdir=options.blog.outdir,
        input_base=options.blog.in_file,
        blog_base=options.blog.out_file,
        )

    if 'EDITOR' in os.environ:
        sh('$EDITOR %s' % blog_file)
    return

Cog扩展

除了 html 和 pdf 任务之外，该软件包还包括用于与cog一起插入命令行程序输出到文档的功能 run_script()

以下使用 run_script() 的reStructuredText源代码示例

.. {{{cog
.. cog.out(run_script(cog.inFile, 'anydbm_whichdb.py'))
.. }}}
.. {{{end}}}

渲染为

.. {{{cog
.. cog.out(run_script(cog.inFile, 'anydbm_whichdb.py'))
.. }}}

::

    $ python anydbm_whichdb.py
    dbhash

.. {{{end}}}

以 .. 开头的行是注释，不会出现在最终的HTML或PDF输出中。

参数

input_file

由cog处理的文件名。通常作为cog.inFile传递。

script_name

与input_file位于同一目录中的Python脚本名称，要运行。如果不使用解释器，这可以是一个完整的命令行。如果使用其他解释器，它可以是其他类型的文件。

interpreter=’python’

用于程序的程序外部解释器。指定‘python’、‘python3’、‘jython’等。

include_prefix=True

布尔值，控制是否包含 :: 前缀。当链式多个命令时，第一个实例通常会使用默认值，后续调用会使用False。

ignore_error=False

布尔值，控制是否忽略错误。如果不忽略，错误将打印到stdout，然后再次运行命令 再次，忽略错误，以便输出最终进入cogged文件。

trailing_newlines=True

布尔值，控制是否将尾随换行符添加到输出。如果为False，则将输出传递给rstrip()然后添加一个换行符。如果为True，则将换行符添加到输出，直到它以2结尾。

break_lines_at=0

表示应在何处断行并继续下一行的整数。默认为0，表示不应执行特殊处理。

line_break_mode=’break’

用于控制如何插入行断开的模式。选项有

‘break’

插入换行符。

‘wrap’

使用textwrap模块分别将每一行包裹到指定的宽度。

‘fill’

使用textwrap模块分别将每一行包裹，插入适当数量的空白字符以保持行左边缘对齐。

‘continue’

插入反斜杠 (\) 和换行符来断行。

‘truncate’

在指定位置断行并丢弃其余部分。

用户

PyMOTW

Python Module of the Week软件包使用Paver和Sphinx构建，包括三种HTML形式和PDF。

virtualenvwrapper

virtualenvwrapper的文档包括包装的HTML和使用替代模板的网站。

历史