Web Support类¶

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)

返回的文档字典包含在模板渲染期间使用的以下项目.

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 是代表评论的dicts列表, 每个都包含以下项目:

Key	内容
文本	评论文本.
用户名	与评论一起存储的用户名.
id	评论的唯一标识符.
评分	评论的当前评级.
年龄	添加评论后的秒数.
时间	包含时间信息的字典. 它包含以下键:年, 月, 日, 小时, 分钟, 秒, iso和delta. iso 是以ISO 8601格式格式化的时间. delta 是评论的年龄的可打印形式(例如, “3 hours ago”).
投票	如果给出 user_id, 这将是表示投票的整数. 1 表示 upvote, -1 表示 downvote, 或 0 表示未投票.
节点	注释附加到的节点的id. 如果注释的父级是另一个注释而不是节点, 则它将为null.
亲	如果未附加到节点, 则附加此注释的注释的id.
孩子	这种格式的所有孩子的列表.
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(). 如果注释附加到节点, 则使用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)[源代码]¶

处理用户的投票. Web支持包依赖于API用户来执行身份验证. API用户通常会从表单接收comment_id和值, 然后确保用户已通过身份验证. 必须传入唯一的用户名, 该用户名还将用于检索用户过去的投票数据. 一个例子, 再一次在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表示upvote, -1表示downvote, 0表示unvote.

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

执行查询 q 的搜索, 并创建一组搜索结果. 然后将搜索结果呈现为html并返回一个上下文字典, 如下所示 get_document():

document = support.get_search_results(q)

参数: q – 搜索查询

目录

上一个主题

下一个主题

本页

Web Support类¶

方法¶