Web 支持快速入门¶
构建文档数据¶
要在您的应用程序中使用 Web 支持包，您需要构建它所使用的数据。这些数据包括表示文档的 pickle 文件、搜索索引和用于跟踪文档中评论及其他内容位置的节点数据。为此，您需要创建一个 WebSupport 类的实例并调用其 build() 方法
from sphinxcontrib.websupport import WebSupport
support = WebSupport(srcdir='/path/to/rst/sources/',
builddir='/path/to/build/outdir',
search='xapian')
support.build()
这将从 srcdir 读取 reStructuredText 源，并将必要的数据放置在 builddir 中。builddir 将包含两个子目录：一个名为“data”，其中包含显示文档、搜索文档和向文档添加评论所需的所有数据。另一个目录将名为“static”，包含应从“/static”提供的静态文件。
注意
如果您希望从“/static”以外的路径提供静态文件，您可以在创建 WebSupport 对象时提供 staticdir 关键字参数。
将 Sphinx 文档集成到您的 Web 应用程序中¶
数据构建完成后，是时候用它做一些有用的事情了。首先为您的应用程序创建一个 WebSupport 对象
from sphinxcontrib.websupport import WebSupport
support = WebSupport(datadir='/path/to/the/data',
search='xapian')
您只需要为每一套要处理的文档准备一个这样的对象。然后您可以调用其 get_document() 方法来访问单个文档
contents = support.get_document('contents')
这将返回一个包含以下项的字典
body：文档的主体，HTML 格式
sidebar：文档的侧边栏，HTML 格式
relbar：一个包含相关文档链接的 div
title：文档标题
css：Sphinx 使用的 CSS 文件链接
script：包含评论选项的 JavaScript
这个字典可以作为模板的上下文使用。目标是易于与您现有的模板系统集成。一个使用 Jinja2 的示例如下
{%- extends "layout.html" %}
{%- block title %}
{{ document.title }}
{%- endblock %}
{% block css %}
{{ super() }}
{{ document.css|safe }}
<link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
{% endblock %}
{%- block script %}
{{ super() }}
{{ document.script|safe }}
{%- endblock %}
{%- block relbar %}
{{ document.relbar|safe }}
{%- endblock %}
{%- block body %}
{{ document.body|safe }}
{%- endblock %}
{%- block sidebar %}
{{ document.sidebar|safe }}
{%- endblock %}
身份验证¶
要使用投票等特定功能，必须能够对用户进行身份验证。身份验证的细节留给您的应用程序。一旦用户通过身份验证，您就可以使用 username 和 moderator 关键字参数将用户的详细信息传递给某些 WebSupport 方法。Web 支持包将存储评论和投票的用户名。唯一的注意事项是，如果您允许用户更改其用户名，则必须更新 websupport 包的数据
support.update_username(old_username, new_username)
username 应是一个唯一标识用户的字符串，而 moderator 应是一个布尔值，表示用户是否具有审核权限。moderator 的默认值为 False。
一个检查用户是否登录然后检索文档的 Flask 函数示例如下
from sphinxcontrib.websupport.errors import *
@app.route('/<path:docname>')
def doc(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)
return render_template('doc.html', document=document)
首先要注意的是，docname 就是请求路径。这使得从单个视图轻松访问正确的文档。如果用户已通过身份验证，则用户名和审核状态会连同 docname 一起传递给 get_document()。Web 支持包随后会将此数据添加到模板中使用的 COMMENT_OPTIONS 中。
注意
这仅在您的文档从文档根目录提供时有效。如果它从另一个目录提供，您将需要用该目录作为 URL 路由的前缀，并在创建 Web 支持对象时提供 docroot 关键字参数
support = WebSupport(..., docroot='docs')
@app.route('/docs/<path:docname>')
执行搜索¶
要使用 Sphinx 侧边栏中内置的搜索表单，请创建一个函数来处理对文档根目录相对的 URL “search” 的请求。用户的搜索查询将位于 GET 参数中，键为 q。然后使用 get_search_results() 方法检索搜索结果。在 Flask 中，它会像这样
@app.route('/search')
def search():
q = request.args.get('q')
document = support.get_search_results(q)
return render_template('doc.html', document=document)
请注意，我们使用与渲染文档相同的模板来渲染搜索结果。这是因为 get_search_results() 返回的上下文字典的格式与 get_document() 返回的相同。
评论审核¶
默认情况下，通过 add_comment() 添加的所有评论都会自动显示。如果您希望进行某种形式的审核，可以传递 displayed 关键字参数
comment = support.add_comment(text, node_id='node_id',
parent_id='parent_id',
username=username, proposal=proposal,
displayed=False)
然后，您可以创建一个新视图来处理评论的审核。当审核员决定接受并显示评论时，将调用此视图
@app.route('/docs/accept_comment', methods=['POST'])
def accept_comment():
moderator = g.user.moderator if g.user else False
comment_id = request.form.get('id')
support.accept_comment(comment_id, moderator=moderator)
return 'OK'
拒绝评论通过删除评论实现。
要在添加新评论但未显示时执行自定义操作（例如向审核员发送电子邮件），您可以在实例化支持对象时向 WebSupport 类传递可调用对象
def moderation_callback(comment):
"""Do something..."""
support = WebSupport(..., moderation_callback=moderation_callback)
审核回调函数必须接受一个参数，该参数将与 WebSupport.add_comment() 返回的评论字典相同。
评论与提案¶
现在完成此操作后，是时候定义处理脚本中 AJAX 调用的函数了。您将需要三个函数。第一个函数用于添加新评论，并将调用 Web 支持方法
add_comment()您会注意到请求中同时发送了
parent_id和node_id。如果评论直接附加到节点，则parent_id将为空。如果评论是另一个评论的子评论，则node_id将为空。接下来的函数处理特定节点的评论检索，并恰当地命名为get_data()所需的最后一个函数将调用
process_vote()，并将处理用户对评论的投票