WebSupport 类¶

class sphinxcontrib.websupport.WebSupport[source]¶

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()[source]¶

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

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

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

WebSupport.get_document(docname, username='', moderator=False)[source]¶

从 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)[source]¶

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

键	内容
text	评论文本。
username	与评论一起存储的用户名。
id	评论的唯一标识符。
rating	评论的当前评分。
age	自评论添加以来经过的时间（秒）。
time	包含时间信息的 dict。它包含以下键：年、月、日、小时、分钟、秒、iso 和 delta。iso 是以 ISO 8601 格式格式化的时间。delta 是评论存在时间的可打印形式（例如“3 小时前”）。
vote	如果给定了 user_id，这将是一个表示投票的整数。1 表示赞成票，-1 表示反对票，如果未投票则为 0。
node	评论所附加到的节点的 ID。如果评论的父级是另一个评论而不是节点，则这将为空。
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)[source]¶

向节点或其他评论添加评论。以与 get_comments() 相同的格式返回评论。如果要将评论附加到节点，请使用 node 关键字参数传入节点的 ID（作为字符串）

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

如果评论是另一个评论的子评论，请使用 parent 关键字参数提供父评论的 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)[source]¶

处理用户的投票。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)[source]¶

执行查询 q 的搜索，并创建一组搜索结果。然后将搜索结果渲染为 html，并返回一个上下文 dict，例如由 get_document() 创建的上下文 dict

document = support.get_search_results(q)

参数:: q – 搜索查询