Web支持类

class sphinxcontrib.websupport.WebSupport

web支持包的主要API类。与web支持包的所有交互都应该通过这个类进行。

该类采用以下关键字参数：

srcdir

包含reStructuredText源文件的目录。

builddir

应该放置构建数据和静态文件的目录。这应该在创建:class:`WebSupport`对象时使用，该对象将用于生成数据。

datadir

Web支持数据所在的目录。在创建将用于检索数据的:class:WebSupport 对象时，应使用此目录。

search

这可能包含引用要使用的内置搜索适配器的字符串（例如 ‘xapian’），或者包含:class:`~.search.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()

Build the documentation. Places the data into the outdir directory. Use it like this:

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

This will read reStructured text files from srcdir. Then it will build the pickles and search index, placing them into builddir. It will also save node data to the database.

WebSupport.get_document(docname, username='', moderator=False)

Load and return a document from a pickle. The document will be a dict object which can be used to render a template:

support = WebSupport(datadir=datadir)
support.get_document('index', username, moderator)

In most cases docname will be taken from the request path and passed directly to this function. In Flask, that would be something like this:

@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)

The document dict that is returned contains the following items to be used during template rendering.

• body：文档的主体为HTML

• sidebar： 文档的侧边栏为HTML

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

• title：文件的标题

• css: Links to css files used by Sphinx

• script: Javascript containing comment options

This raises DocumentNotFoundError if a document matching docname is not found.

参数:

docname – the name of the document to load.

WebSupport.get_data(node_id, username=None, moderator=False)

Get the comments and source associated with node_id. If username is given vote information will be included with the returned comments. The default CommentBackend returns a dict with two keys, source, and comments. source is raw source of the node and is used as the starting point for proposals a user can add. comments is a list of dicts that represent a comment, each having the following items:

Key	目录
text	The comment text.
username	The username that was stored with the comment.
id	The comment’s unique identifier.
rating	The comment’s current rating.
age	The time in seconds since the comment was added.
time	A dict containing time information. It contains the following keys: year, month, day, hour, minute, second, iso, and delta. iso is the time formatted in ISO 8601 format. delta is a printable form of how old the comment is (e.g. “3 hours ago”).
vote	If user_id was given, this will be an integer representing the vote. 1 for an upvote, -1 for a downvote, or 0 if unvoted.
node	The id of the node that the comment is attached to. If the comment’s parent is another comment rather than a node, this will be null.
parent	The id of the comment that this comment is attached to if it is not attached to a node.
children	A list of all children, in this format.
proposal_diff	An HTML representation of the differences between the the current source and the user’s proposed source.

参数:

• node_id – the id of the node to get comments for.

• username – the username of the user viewing the comments.

• moderator – whether the user is a moderator.

WebSupport.add_comment(text, node_id='', parent_id='', displayed=True, username=None, time=None, proposal=None, moderator=False)

Add a comment to a node or another comment. Returns the comment in the same format as get_comments(). If the comment is being attached to a node, pass in the node’s id (as a string) with the node keyword argument:

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

If the comment is the child of another comment, provide the parent’s id (as a string) with the parent keyword argument:

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

If you would like to store a username with the comment, pass in the optional username keyword argument:

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

参数:

• parent_id – the prefixed id of the comment’s parent.

• text – the text of the comment.

• displayed – for moderation purposes

• username – the username of the user making the comment.

• time – the time the comment was created, defaults to now.

WebSupport.process_vote(comment_id, username, value)

Process a user’s vote. The web support package relies on the API user to perform authentication. The API user will typically receive a comment_id and value from a form, and then make sure the user is authenticated. A unique username must be passed in, which will also be used to retrieve the user’s past voting data. An example, once again in 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 – the comment being voted on

• username – the unique username of the user voting

• value – 1 for an upvote, -1 for a downvote, 0 for an unvote.

WebSupport.get_search_results(q)

Perform a search for the query q, and create a set of search results. Then render the search results as html and return a context dict like the one created by get_document():

document = support.get_search_results(q)

参数:

q – the search query