Web 支持快速入门

构建文档数据

要在您的应用程序中使用 web 支持包,您需要构建它所使用的数据.这些数据包括表示文档的 pickle 文件、搜索索引以及用于跟踪文档中评论和其他内容位置的节点数据.为此,您需要创建一个 :class :~.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 应用程序中

现在数据已经构建好了,是时候对其进行一些有用的操作了.首先,为您的应用程序创建一个 :class :~.WebSupport 对象:

from sphinxcontrib.websupport import WebSupport

support = WebSupport(datadir='/path/to/the/data',
                     search='xapian')

每个文档集只需要其中之一.然后,您可以调用其 :meth :~.WebSupport.get_document 方法来访问单个文档:

contents = support.get_document('contents')

这将返回一个包含以下项目的字典:

• body: 文档的主要部分以HTML格式呈现

• sidebar: 文档的侧边栏,格式为HTML

• relbar: 一个包含相关文档链接的 div

• title: 文档的标题

• css: Sphinx使用的CSS文件链接

• 脚本: 包含注释选项的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 关键字参数将用户的详细信息传递给某些 :class :~.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() .然后,网络支持包将把这些数据添加到模板中使用的 COMMENT_OPTIONS .

备注

这仅在您的文档从文档根目录提供时有效.如果它从另一个目录提供,您需要在 url 路由前加上该目录,并在创建 web 支持对象时提供 docroot 关键字参数:

support = WebSupport(..., docroot='docs')

@app.route('/docs/<path:docname>')

执行搜索

要使用内置于 Sphinx 侧边栏的搜索表单,请创建一个函数来处理相对于文档根的 URL ‘search’ 的请求.用户的搜索查询将存放在 GET 参数中,键为 q .然后使用 :meth :~sphinxcontrib.websupport.WebSupport.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() 相同.

评论与提案

完成这些后,是时候定义处理来自脚本的AJAX调用的函数了.你需要三个函数.第一个函数用于添加新评论,将调用网络支持方法 :meth :~.WebSupport.add_comment

@app.route('/docs/add_comment', methods=['POST'])
def add_comment():
    parent_id = request.form.get('parent', '')
    node_id = request.form.get('node', '')
    text = request.form.get('text', '')
    proposal = request.form.get('proposal', '')
    username = g.user.name if g.user is not None else 'Anonymous'
    comment = support.add_comment(text, node_id='node_id',
                                  parent_id='parent_id',
                                  username=username, proposal=proposal)
    return jsonify(comment=comment)

您会注意到请求中同时发送了 parent_id 和 node_id .如果评论是直接添加到一个节点上,则 parent_id 将为空.如果评论是另一个评论的子评论,则 node_id 将为空.接下来的函数处理特定节点的评论检索,名字恰当地命名为 :meth :~sphinxcontrib.websupport.WebSupport.get_data

@app.route('/docs/get_comments')
def get_comments():
    username = g.user.name if g.user else None
    moderator = g.user.moderator if g.user else False
    node_id = request.args.get('node', '')
    data = support.get_data(node_id, username, moderator)
    return jsonify(**data)

最终需要的函数将会调用 :meth :~.WebSupport.process_vote ,并处理用户对评论的投票:

@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.id, value)
    return "success"

评论审核

默认情况下,通过 :meth :~.WebSupport.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'

拒绝评论通过删除评论来实现.

当添加新的评论但未显示时,要执行自定义操作（例如发送电子邮件给版主）,可以在实例化支持对象时,将可调用对象传递给 :class :~.WebSupport 类:

def moderation_callback(comment):
    """Do something..."""

support = WebSupport(..., moderation_callback=moderation_callback)

审查回调必须接受一个参数,该参数将是:meth:.WebSupport.add_comment 返回的相同评论字典.

Previous

Sphinx网页支持

Next

WebSupport 类