WebSupport 类

class sphinxcontrib.websupport.WebSupport[source]

网页支持包的主要 API 类。所有与网页支持包的交互都应通过此类进行。

该类接受以下关键字参数

srcdir

包含 reStructuredText 源文件的目录。

builddir

构建数据和静态文件应放置到的目录。在创建将用于构建数据的 WebSupport 对象时,应使用此目录。

datadir

网页支持数据所在的目录。在创建将用于检索数据的 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 读取 reStructuredText 文件。然后它将构建 pickle 和搜索索引,并将它们放置到 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 返回一个包含两个键的字典,sourcecommentssource 是节点的原始源代码,用作用户可以添加的建议的起点。comments 是一个表示评论的字典列表,每个字典都包含以下项目

内容

text

评论文本。

username

与评论一起存储的用户名。

id

评论的唯一标识符。

rating

评论的当前评分。

age

自添加评论以来经过的秒数。

time

包含时间信息的字典。它包含以下键:year、month、day、hour、minute、second、iso 和 delta。iso 是以 ISO 8601 格式设置的时间。delta 是评论有多旧的可打印形式(例如,“3 小时前”)。

vote

如果提供了 user_id,这将是一个表示投票的整数。1 表示赞成票,-1 表示反对票,或 0 表示未投票。

node

评论所附着的节点的 ID。如果评论的父级是另一个评论而不是节点,则此值为 null。

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]

处理用户的投票。网页支持包依赖于 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 – 正在被投票的评论ID

  • username – 投票用户的唯一用户名

  • value – 1 代表赞成票,-1 代表反对票,0 代表取消投票。

WebSupport.get_search_results(q)[source]

对查询 q 执行搜索,并创建一组搜索结果。然后将搜索结果渲染为 html 并返回一个上下文字典,类似于由 get_document() 创建的字典。

document = support.get_search_results(q)
参数:

q – 搜索查询