网络支持类

class sphinxcontrib.websupport.WebSupport[源代码]

Web支持包的主API类。与Web支持包的所有交互都应通过此课程进行。

该类接受以下关键字参数：

源目录

包含reStrufiredText源文件的目录。

构建目录

构建数据和静态文件的目录应该放在其中。在创建 WebSupport 对象，该对象将用于生成数据。

数据目录

Web支持数据所在的目录。在创建 WebSupport 对象，该对象将用于检索数据。

搜索

它可以包含引用要使用的内置搜索适配器的字符串(例如‘xapian’)，也可以包含 BaseSearch 。

存储

它可以包含表示数据库uri的字符串，也可以包含 StorageBackend 。如果未提供此选项，则将创建一个新的SQLite数据库。

moderation_callback

添加未显示的新注释时要调用的Callable。它必须接受一个参数：表示添加的注释的词典。

静态目录

如果应在不同位置创建静态文件 and not in '/static' ，这应该是一个包含该位置名称的字符串(例如 builddir + '/static_files' )。

备注

如果您指定 staticdir ，您通常会希望调整 staticroot 相应地。

统计根

如果静态文件不是从 '/static' ，这应该是一个包含该位置名称的字符串(例如 '/static_files' )。

文档根

如果文档不是从URL的基本路径提供的，则这应该是指定该路径的字符串(例如 'docs' )。

在 1.6 版本发生变更: WebSupport类已从sphinx.webSupport移至sphinxcontri.webSupport。请加上 sphinxcontrib-websupport 将依赖项打包并改用已移动的类。

方法

WebSupport.build()[源代码]

构建文档。将数据放入 outdir 目录.这样使用：：

support = WebSupport(srcdir, builddir, search='xapian')
support.build()

这将读取重新结构化的文本文件 srcdir .然后它会构建泡菜和搜索索引，将它们放入 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)

返回的文档dict包含以下要在模板渲染期间使用的项。

  • body ：文档主体形式为HTML

  • sidebar ：文档的侧边栏为HTML

  • relbar ：包含相关文档链接的版块

  • title ：文件标题

  • css ：指向Sphinx使用的css文件的链接

  • script ：包含评论选项的JavaScript

这就提出 DocumentNotFoundError 如果文档匹配 docname 没有找到。

参数:

docname -- 要加载的文档的名称。

WebSupport.get_data(node_id, username=None, moderator=False)[源代码]

获取与之相关的评论和来源 node_id .如果 username 投票信息将包含在返回的评论中。默认的CommentBackend返回具有两个键的dict， source ，而且 comments . source 是节点的原始源代码，用作用户可以添加建议的起点。 comments 是代表评论的句子列表，每个句子都有以下项：

关键

内容

文本

评论文本。

用户名

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

ID

评论的唯一标识符。

评级

该评论的当前评级。

年龄

添加评论以来的时间（秒）。

时间

包含时间信息的法令。它包含以下键：年、月、日、小时、分钟、秒、iso和Delta。 iso 是ISO 8601格式的时间。 delta 是评论的年龄的可打印形式（例如“3小时前”）。

投票

如果 user_id 如果给出，这将是代表投票的一个整数。1表示赞成票，-1表示反对票，如果未投票，则为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() .如果注释附加到节点，请通过节点关键字参数传递节点的id（作为字符串）：：

comment = support.add_comment(text, node_id=node_id)

如果评论是另一个评论的子条，请提供父条的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表示赞成，-1表示反对，0表示反对。

WebSupport.get_search_results(q)[源代码]

对查询执行搜索 q ，并创建一组搜索结果。然后将搜索结果呈现为html并返回一个类似于由 get_document()

document = support.get_search_results(q)
参数:

q -- 搜索查询