<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Web Support Quick Start — Sphinx 1.1.3 documentation</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.1.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Sphinx 1.1.3 documentation"
href="../_static/opensearch.xml"/>
<link rel="top" title="Sphinx 1.1.3 documentation" href="../index.html" />
<link rel="up" title="Sphinx Web Support" href="../websupport.html" />
<link rel="next" title="The WebSupport Class" href="api.html" />
<link rel="prev" title="Sphinx Web Support" href="../websupport.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<img src="../_static/sphinx.png" alt="Sphinx logo" />
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="api.html" title="The WebSupport Class"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../websupport.html" title="Sphinx Web Support"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../websupport.html" accesskey="U">Sphinx Web Support</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Web Support Quick Start</a><ul>
<li><a class="reference internal" href="#building-documentation-data">Building Documentation Data</a></li>
<li><a class="reference internal" href="#integrating-sphinx-documents-into-your-webapp">Integrating Sphinx Documents Into Your Webapp</a><ul>
<li><a class="reference internal" href="#authentication">Authentication</a></li>
</ul>
</li>
<li><a class="reference internal" href="#performing-searches">Performing Searches</a></li>
<li><a class="reference internal" href="#comments-proposals">Comments & Proposals</a></li>
<li><a class="reference internal" href="#comment-moderation">Comment Moderation</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../websupport.html"
title="previous chapter">Sphinx Web Support</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="api.html"
title="next chapter">The WebSupport Class</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/web/quickstart.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="web-support-quick-start">
<span id="websupportquickstart"></span><h1>Web Support Quick Start<a class="headerlink" href="#web-support-quick-start" title="Permalink to this headline">¶</a></h1>
<div class="section" id="building-documentation-data">
<h2>Building Documentation Data<a class="headerlink" href="#building-documentation-data" title="Permalink to this headline">¶</a></h2>
<p>To make use of the web support package in your application you’ll need to build
the data it uses. This data includes pickle files representing documents,
search indices, and node data that is used to track where comments and other
things are in a document. To do this you will need to create an instance of the
<a class="reference internal" href="api.html#sphinx.websupport.WebSupport" title="sphinx.websupport.WebSupport"><tt class="xref py py-class docutils literal"><span class="pre">WebSupport</span></tt></a> class and call its <a class="reference internal" href="api.html#sphinx.websupport.WebSupport.build" title="sphinx.websupport.WebSupport.build"><tt class="xref py py-meth docutils literal"><span class="pre">build()</span></tt></a> method:</p>
<div class="highlight-python"><pre>from sphinx.websupport import WebSupport
support = WebSupport(srcdir='/path/to/rst/sources/',
builddir='/path/to/build/outdir',
search='xapian')
support.build()</pre>
</div>
<p>This will read reStructuredText sources from <cite>srcdir</cite> and place the necessary
data in <cite>builddir</cite>. The <cite>builddir</cite> will contain two sub-directories: one named
“data” that contains all the data needed to display documents, search through
documents, and add comments to documents. The other directory will be called
“static” and contains static files that should be served from “/static”.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you wish to serve static files from a path other than “/static”, you can
do so by providing the <em>staticdir</em> keyword argument when creating the
<a class="reference internal" href="api.html#sphinx.websupport.WebSupport" title="sphinx.websupport.WebSupport"><tt class="xref py py-class docutils literal"><span class="pre">WebSupport</span></tt></a> object.</p>
</div>
</div>
<div class="section" id="integrating-sphinx-documents-into-your-webapp">
<h2>Integrating Sphinx Documents Into Your Webapp<a class="headerlink" href="#integrating-sphinx-documents-into-your-webapp" title="Permalink to this headline">¶</a></h2>
<p>Now that the data is built, it’s time to do something useful with it. Start off
by creating a <a class="reference internal" href="api.html#sphinx.websupport.WebSupport" title="sphinx.websupport.WebSupport"><tt class="xref py py-class docutils literal"><span class="pre">WebSupport</span></tt></a> object for your application:</p>
<div class="highlight-python"><pre>from sphinx.websupport import WebSupport
support = WebSupport(datadir='/path/to/the/data',
search='xapian')</pre>
</div>
<p>You’ll only need one of these for each set of documentation you will be working
with. You can then call it’s <a class="reference internal" href="api.html#sphinx.websupport.WebSupport.get_document" title="sphinx.websupport.WebSupport.get_document"><tt class="xref py py-meth docutils literal"><span class="pre">get_document()</span></tt></a> method to access
individual documents:</p>
<div class="highlight-python"><pre>contents = support.get_document('contents')</pre>
</div>
<p>This will return a dictionary containing the following items:</p>
<ul class="simple">
<li><strong>body</strong>: The main body of the document as HTML</li>
<li><strong>sidebar</strong>: The sidebar of the document as HTML</li>
<li><strong>relbar</strong>: A div containing links to related documents</li>
<li><strong>title</strong>: The title of the document</li>
<li><strong>css</strong>: Links to css files used by Sphinx</li>
<li><strong>js</strong>: Javascript containing comment options</li>
</ul>
<p>This dict can then be used as context for templates. The goal is to be easy to
integrate with your existing templating system. An example using <a class="reference external" href="http://jinja.pocoo.org/">Jinja2</a> is:</p>
<div class="highlight-html+jinja"><pre>{%- extends "layout.html" %}
{%- block title %}
{{ document.title }}
{%- endblock %}
{% block css %}
{{ super() }}
{{ document.css|safe }}
<link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
{% endblock %}
{%- block js %}
{{ super() }}
{{ document.js|safe }}
{%- endblock %}
{%- block relbar %}
{{ document.relbar|safe }}
{%- endblock %}
{%- block body %}
{{ document.body|safe }}
{%- endblock %}
{%- block sidebar %}
{{ document.sidebar|safe }}
{%- endblock %}</pre>
</div>
<div class="section" id="authentication">
<h3>Authentication<a class="headerlink" href="#authentication" title="Permalink to this headline">¶</a></h3>
<p>To use certain features such as voting, it must be possible to authenticate
users. The details of the authentication are left to your application. Once a
user has been authenticated you can pass the user’s details to certain
<a class="reference internal" href="api.html#sphinx.websupport.WebSupport" title="sphinx.websupport.WebSupport"><tt class="xref py py-class docutils literal"><span class="pre">WebSupport</span></tt></a> methods using the <em>username</em> and <em>moderator</em> keyword
arguments. The web support package will store the username with comments and
votes. The only caveat is that if you allow users to change their username you
must update the websupport package’s data:</p>
<div class="highlight-python"><pre>support.update_username(old_username, new_username)</pre>
</div>
<p><em>username</em> should be a unique string which identifies a user, and <em>moderator</em>
should be a boolean representing whether the user has moderation privilieges.
The default value for <em>moderator</em> is <em>False</em>.</p>
<p>An example <a class="reference external" href="http://flask.pocoo.org/">Flask</a> function that checks whether a
user is logged in and then retrieves a document is:</p>
<div class="highlight-python"><pre>from sphinx.websupport.errors import *
@app.route('/<path:docname>')
def doc(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)
return render_template('doc.html', document=document)</pre>
</div>
<p>The first thing to notice is that the <em>docname</em> is just the request path. This
makes accessing the correct document easy from a single view. If the user is
authenticated, then the username and moderation status are passed along with the
docname to <a class="reference internal" href="api.html#sphinx.websupport.WebSupport.get_document" title="sphinx.websupport.WebSupport.get_document"><tt class="xref py py-meth docutils literal"><span class="pre">get_document()</span></tt></a>. The web support package will then
add this data to the <tt class="docutils literal"><span class="pre">COMMENT_OPTIONS</span></tt> that are used in the template.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>This only works works if your documentation is served from your
document root. If it is served from another directory, you will
need to prefix the url route with that directory, and give the <cite>docroot</cite>
keyword argument when creating the web support object:</p>
<div class="last highlight-python"><pre>support = WebSupport(..., docroot='docs')
@app.route('/docs/<path:docname>')</pre>
</div>
</div>
</div>
</div>
<div class="section" id="performing-searches">
<h2>Performing Searches<a class="headerlink" href="#performing-searches" title="Permalink to this headline">¶</a></h2>
<p>To use the search form built-in to the Sphinx sidebar, create a function to
handle requests to the url ‘search’ relative to the documentation root. The
user’s search query will be in the GET parameters, with the key <cite>q</cite>. Then use
the <a class="reference internal" href="api.html#sphinx.websupport.WebSupport.get_search_results" title="sphinx.websupport.WebSupport.get_search_results"><tt class="xref py py-meth docutils literal"><span class="pre">get_search_results()</span></tt></a> method to retrieve
search results. In <a class="reference external" href="http://flask.pocoo.org/">Flask</a> that would be like this:</p>
<div class="highlight-python"><pre>@app.route('/search')
def search():
q = request.args.get('q')
document = support.get_search_results(q)
return render_template('doc.html', document=document)</pre>
</div>
<p>Note that we used the same template to render our search results as we did to
render our documents. That’s because <a class="reference internal" href="api.html#sphinx.websupport.WebSupport.get_search_results" title="sphinx.websupport.WebSupport.get_search_results"><tt class="xref py py-meth docutils literal"><span class="pre">get_search_results()</span></tt></a>
returns a context dict in the same format that <a class="reference internal" href="api.html#sphinx.websupport.WebSupport.get_document" title="sphinx.websupport.WebSupport.get_document"><tt class="xref py py-meth docutils literal"><span class="pre">get_document()</span></tt></a>
does.</p>
</div>
<div class="section" id="comments-proposals">
<h2>Comments & Proposals<a class="headerlink" href="#comments-proposals" title="Permalink to this headline">¶</a></h2>
<p>Now that this is done it’s time to define the functions that handle the AJAX
calls from the script. You will need three functions. The first function is
used to add a new comment, and will call the web support method
<a class="reference internal" href="api.html#sphinx.websupport.WebSupport.add_comment" title="sphinx.websupport.WebSupport.add_comment"><tt class="xref py py-meth docutils literal"><span class="pre">add_comment()</span></tt></a>:</p>
<div class="highlight-python"><pre>@app.route('/docs/add_comment', methods=['POST'])
def add_comment():
parent_id = request.form.get('parent', '')
node_id = request.form.get('node', '')
text = request.form.get('text', '')
proposal = request.form.get('proposal', '')
username = g.user.name if g.user is not None else 'Anonymous'
comment = support.add_comment(text, node_id='node_id',
parent_id='parent_id',
username=username, proposal=proposal)
return jsonify(comment=comment)</pre>
</div>
<p>You’ll notice that both a <cite>parent_id</cite> and <cite>node_id</cite> are sent with the
request. If the comment is being attached directly to a node, <cite>parent_id</cite>
will be empty. If the comment is a child of another comment, then <cite>node_id</cite>
will be empty. Then next function handles the retrieval of comments for a
specific node, and is aptly named
<a class="reference internal" href="api.html#sphinx.websupport.WebSupport.get_data" title="sphinx.websupport.WebSupport.get_data"><tt class="xref py py-meth docutils literal"><span class="pre">get_data()</span></tt></a>:</p>
<div class="highlight-python"><pre>@app.route('/docs/get_comments')
def get_comments():
username = g.user.name if g.user else None
moderator = g.user.moderator if g.user else False
node_id = request.args.get('node', '')
data = support.get_data(node_id, username, moderator)
return jsonify(**data)</pre>
</div>
<p>The final function that is needed will call <a class="reference internal" href="api.html#sphinx.websupport.WebSupport.process_vote" title="sphinx.websupport.WebSupport.process_vote"><tt class="xref py py-meth docutils literal"><span class="pre">process_vote()</span></tt></a>,
and will handle user votes on comments:</p>
<div class="highlight-python"><pre>@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.id, value)
return "success"</pre>
</div>
</div>
<div class="section" id="comment-moderation">
<h2>Comment Moderation<a class="headerlink" href="#comment-moderation" title="Permalink to this headline">¶</a></h2>
<p>By default, all comments added through <a class="reference internal" href="api.html#sphinx.websupport.WebSupport.add_comment" title="sphinx.websupport.WebSupport.add_comment"><tt class="xref py py-meth docutils literal"><span class="pre">add_comment()</span></tt></a> are
automatically displayed. If you wish to have some form of moderation, you can
pass the <cite>displayed</cite> keyword argument:</p>
<div class="highlight-python"><pre>comment = support.add_comment(text, node_id='node_id',
parent_id='parent_id',
username=username, proposal=proposal,
displayed=False)</pre>
</div>
<p>You can then create a new view to handle the moderation of comments. It
will be called when a moderator decides a comment should be accepted and
displayed:</p>
<div class="highlight-python"><pre>@app.route('/docs/accept_comment', methods=['POST'])
def accept_comment():
moderator = g.user.moderator if g.user else False
comment_id = request.form.get('id')
support.accept_comment(comment_id, moderator=moderator)
return 'OK'</pre>
</div>
<p>Rejecting comments happens via comment deletion.</p>
<p>To perform a custom action (such as emailing a moderator) when a new comment is
added but not displayed, you can pass callable to the <a class="reference internal" href="api.html#sphinx.websupport.WebSupport" title="sphinx.websupport.WebSupport"><tt class="xref py py-class docutils literal"><span class="pre">WebSupport</span></tt></a>
class when instantiating your support object:</p>
<div class="highlight-python"><pre>def moderation_callback(comment):
"""Do something..."""
support = WebSupport(..., moderation_callback=moderation_callback)</pre>
</div>
<p>The moderation callback must take one argument, which will be the same comment
dict that is returned by <tt class="xref py py-meth docutils literal"><span class="pre">add_comment()</span></tt>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="api.html" title="The WebSupport Class"
>next</a> |</li>
<li class="right" >
<a href="../websupport.html" title="Sphinx Web Support"
>previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../websupport.html" >Sphinx Web Support</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011, Georg Brandl.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
distrib
>
Mageia
>
4
>
i586
>
media
>
core-release
>
by-pkgid
>
c95717a2237548a7bdaddf39c85b0f0f
>
files
>
144
