The WebSupport Class

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.

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: The main body of the document as HTML
• sidebar: The sidebar of the document as HTML
• relbar: A div containing links to related documents
• title: The title of the document
• css: Links to css files used by Sphinx
• script: Javascript containing comment options

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

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:

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)

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"

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)