WebSupport类¶

class sphinxcontrib.websupport.WebSupport[源代码]¶

web支持包的主要API类。与web支持包的所有交互都应该通过这个类进行。

该类采用以下关键字参数：

srcdir: 包含reStructuredText源文件的目录。
builddir: 应该放置构建数据和静态文件的目录。这应该在创建 WebSupport 对象时使用，该对象将用于生成数据。
datadir: Web支持数据所在的目录。在创建将用于检索数据的 WebSupport 对象时，应使用此目录。
search: 这可能包含引用要使用的内置搜索适配器的字符串（例如 ‘xapian’），或者包含 BaseSearch 的子类实例。
storage: 这可能包含表示数据库 uri 的字符串或子类的实例 StorageBackend。如果未提供, 则将创建新的sqlite数据库。
moderation_callback: 添加新注释时要调用的可调用项。它必须接受一个参数：表示已添加注释的字典。
staticdir: 如果静态文件应该在不同的位置，而不是 在 '/static' 中创建，那么这应该是一个带有该位置名称的字符串（例如 builddir + '/static_files'）。

备注

如果您指定了 staticdir，则通常需要相应地调整 staticroot。
staticroot: 如果静态文件不是来自 '/static'，那么这应该是一个带有该位置名称的字符串（例如 '/static_files'）。
docroot: 如果文档不是从URL的基本路径提供的，那么这应该是指定该路径的字符串（例如 'docs'）。

在 1.6 版本发生变更: WebSupport 类从 sphinx.websupport 移至 sphinxcontrib.websupport。请在您的依赖项中添加 sphinxcontrib-websupport 包，然后使用移动的类。

方法¶

WebSupport.build()[源代码]¶

构建文档。将数据放入 outdir 目录中。像这样使用它:

support = WebSupport(srcdir, builddir, search='xapian')
support.build()

这将从 srcdir 读取 reStructured 文本文件。然后它将构建 pickles 和搜索索引，将它们放入 builddir。它还将节点数据保存到数据库中。

WebSupport.get_document(docname, username='', moderator=False)[源代码]¶

从pickle加载并返回文档。该文档将是一个dict对象，可用于渲染模板:

support = WebSupport(datadir=datadir)
support.get_document('index', username, moderator)

在大多数情况下，docname 将从请求路径中获取并直接传递给此函数。在Flask中，这将类似于:

@app.route('/<path:docname>')
def index(docname):
    username = g.user.name if g.user else ''
    moderator = g.user.moderator if g.user else False
    try:
        document = support.get_document(docname, username,
                                        moderator)
    except DocumentNotFoundError:
        abort(404)
    render_template('doc.html', document=document)

返回的文档dict包含以下项目，可在模板渲染期间使用。

body：文档的主体为HTML
sidebar：文档的侧边栏为HTML
relbar：包含相关文档链接的div
title：文件的标题
css：Sphinx使用的css文件的链接
script：包含注释选项的Javascript

如果未找到与 docname 匹配的文档，则会引发 DocumentNotFoundError。

参数:: docname -- 要加载的文档的名称。

WebSupport.get_data(node_id, username=None, moderator=False)[源代码]¶

获取与 node_id 关联的注释和源代码。如果提供了 username，则返回的注释将包含投票信息。默认的 CommentBackend 返回一个包含两个键的字典， source 和 comments。source 是节点的原始源代码，用作用户可以添加的提案的起点。comments 是表示注释的字典列表，每个字典具有以下项目：

键名	目录
text	评论文本。
username	和评论一起存储的用户名。
id	评论的唯一标识符。
rating	评论的当前评分。
age	自添加评论以来的秒数。
time	包含时间信息的字典。它包含以下键：year、month、day、hour、minute、second、iso 和 delta。iso 是以 ISO 8601 格式格式化的时间。delta 是评论的年龄的可打印形式（例如“3小时前”）。
vode	如果提供了 user_id，则这将是一个表示投票的整数。1表示赞成票，-1表示反对票，0表示未投票。
node	评论附加到的节点的ID。如果评论的父级是另一个评论而不是节点，则此值将为null。
parent	如果该评论未附加到节点，则为该评论附加的评论的ID。
children	所有子项的列表，格式如下。
proposal_diff	当前源和用户提议的源之间差异的HTML表示形式。

参数:

node_id -- 要获取评论的节点的ID。
username -- 查看评论的用户的用户名。
moderator -- 用户是否为版主。

WebSupport.add_comment(text, node_id='', parent_id='', displayed=True, username=None, time=None, proposal=None, moderator=False)[源代码]¶

向节点或另一个注释添加注释。以与 get_comments() 相同的格式返回注释。如果注释附加到节点，则使用节点关键字参数传入节点的ID（作为字符串）:

comment = support.add_comment(text, node_id=node_id)

如果注释是另一个注释的子项，请使用父关键字参数提供父项的ID（作为字符串）:

comment = support.add_comment(text, parent_id=parent_id)

如果您想将用户名存储在注释中，请传入可选的 username 关键字参数:

comment = support.add_comment(text, node=node_id,
                              username=username)

参数:

parent_id -- 评论父项的前缀ID。
text -- 评论的文本。
displayed -- 用于审核目的
username -- 发表评论的用户的用户名。
time -- 评论创建的时间，默认为现在。

WebSupport.process_vote(comment_id, username, value)[源代码]¶

处理用户的投票。Web 支持包依赖于 API 用户执行身份验证。API 用户通常会从表单中接收 comment_id 和 value，然后确保用户已通过身份验证。必须传递唯一的用户名，这也将用于检索用户的过去投票数据。再次在 Flask 中的示例:

@app.route('/docs/process_vote', methods=['POST'])
def process_vote():
    if g.user is None:
        abort(401)
    comment_id = request.form.get('comment_id')
    value = request.form.get('value')
    if value is None or comment_id is None:
        abort(400)
    support.process_vote(comment_id, g.user.name, value)
    return "success"

参数:

comment_id -- 正在投票的评论
username -- 投票用户的唯一用户名
value -- 1表示赞成票，-1表示反对票，0表示取消投票。

WebSupport.get_search_results(q)[源代码]¶

对查询 q 执行搜索，并创建一组搜索结果。然后将搜索结果呈现为html并返回一个上下文字典，就像 get_document() 创建的那样:

document = support.get_search_results(q)

参数:: q -- 搜索查询