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()
这将从中读取 reStructuredText 源 srcdir
把必要的数据放到 builddir
. 这个 builddir
将包含两个子目录:一个名为“数据”,包含显示文档、搜索文档和向文档添加注释所需的所有数据。另一个目录将被称为“static”,其中包含应从“/static”提供服务的静态文件。
备注
如果您希望从除“/static”之外的路径提供静态文件,可以通过提供 静音 创建时的关键字参数 WebSupport
对象。
将Sphinx文档集成到您的webapp中¶
既然已经构建了数据,现在是时候对它做些有用的事情了。从创建 WebSupport
应用程序的对象:
from sphinxcontrib.websupport import WebSupport
support = WebSupport(datadir='/path/to/the/data',
search='xapian')
对于您将要使用的每一组文档,您只需要其中一个。你可以称之为 get_document()
访问单个文档的方法:
contents = support.get_document('contents')
这将返回包含以下项的字典:
body :作为HTML的文档主体
侧边栏 :文档的边栏为HTML
雷巴 :包含相关文档链接的DIV
标题 :文档标题
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 %}
认证¶
要使用投票等某些功能,必须能够对用户进行身份验证。身份验证的详细信息留给您的应用程序。一旦用户通过身份验证,您就可以将用户的详细信息传递给 WebSupport
方法使用 用户名 和 慢化剂 关键字参数。Web支持包将用注释和投票存储用户名。唯一需要注意的是,如果您允许用户更改其用户名,则必须更新WebSupport包的数据::
support.update_username(old_username, new_username)
用户名 应该是标识用户的唯一字符串,并且 慢化剂 应该是一个布尔值,表示用户是否具有仲裁特权。的默认值 慢化剂 是 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一起传递给 get_document()
. 然后,Web支持包将此数据添加到 COMMENT_OPTIONS
模板中使用的。
备注
只有当您的文档是从您的文档根目录提供的时,这才有效。如果它是从另一个目录提供的,则需要在url路由前面加上该目录的前缀,并给 docroot 创建Web支持对象时的关键字参数::
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()
返回一个上下文dict,其格式与 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'
通过删除注释来拒绝注释。
若要在添加但不显示新评论时执行自定义操作(例如,向版主发送电子邮件),可以将Callable传递给 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
将是空的。然后,next函数处理对特定节点的注释的检索,并恰当地命名get_data()
::所需的最后一个函数将调用
process_vote()
,并将处理用户对评论的投票::