IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Removed trailing whitespace

Browse Source
This commit is contained in:
Daniel Neuhäuser 2010-08-10 17:11:11 +02:00
parent d77cbf3043
commit 023f342bed
15 changed files with 177 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
doc/web/api.rst
View File

@ -7,48 +7,48 @@ The WebSupport Class
.. class:: WebSupport
The main API class for the web support package. All interactions
with the web support package should occur through this class.
The main API class for the web support package. All interactions
with the web support package should occur through this class.
The class takes the following keyword arguments:
The class takes the following keyword arguments:
srcdir
The directory containing reStructuredText source files.
srcdir
The directory containing reStructuredText source files.
builddir
The directory that build data and static files should be placed in.
This should be used when creating a :class:`WebSupport` object that
will be used to build data.
builddir
The directory that build data and static files should be placed in.
This should be used when creating a :class:`WebSupport` object that
will be used to build data.
datadir:
The directory that the web support data is in. This should be used
when creating a :class:`WebSupport` object that will be used to
retrieve data.
datadir:
The directory that the web support data is in. This should be used
when creating a :class:`WebSupport` object that will be used to
retrieve data.
search:
This may contain either a string (e.g. 'xapian') referencing a
built-in search adapter to use, or an instance of a subclass of
:class:`~sphinx.websupport.search.BaseSearch`.
search:
This may contain either a string (e.g. 'xapian') referencing a
built-in search adapter to use, or an instance of a subclass of
:class:`~sphinx.websupport.search.BaseSearch`.
storage:
This may contain either a string representing a database uri, or an
instance of a subclass of
:class:`~sphinx.websupport.storage.StorageBackend`. If this is not
provided a new sqlite database will be created.
storage:
This may contain either a string representing a database uri, or an
instance of a subclass of
:class:`~sphinx.websupport.storage.StorageBackend`. If this is not
provided a new sqlite database will be created.
moderation_callback:
A callable to be called when a new comment is added that is not
displayed. It must accept one argument: a dict representing the
comment that was added.
moderation_callback:
A callable to be called when a new comment is added that is not
displayed. It must accept one argument: a dict representing the
comment that was added.
staticdir:
If static files are served from a location besides "/static", this
should be a string with the name of that location
(e.g. '/static_files').
staticdir:
If static files are served from a location besides "/static", this
should be a string with the name of that location
(e.g. '/static_files').
docroot:
If the documentation is not served from the base path of a URL, this
should be a string specifying that path (e.g. 'docs')
docroot:
If the documentation is not served from the base path of a URL, this
should be a string specifying that path (e.g. 'docs')
Methods
~~~~~~~
@ -64,4 +64,3 @@ Methods
.. automethod:: sphinx.websupport.WebSupport.process_vote
.. automethod:: sphinx.websupport.WebSupport.get_search_results

70
doc/web/quickstart.rst
View File

@ -17,7 +17,7 @@ class and call it's :meth:`~sphinx.websupport.WebSupport.build` method::
support = WebSupport(srcdir='/path/to/rst/sources/',
builddir='/path/to/build/outdir',
search='xapian')
search='xapian')
support.build()
@ -71,30 +71,30 @@ easy to integrate with your existing templating system. An example using
{%- extends "layout.html" %}
{%- block title %}
{{ document.title }}
{{ document.title }}
{%- endblock %}
{% block css %}
{{ super() }}
{{ document.css|safe }}
<link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
{{ super() }}
{{ document.css|safe }}
<link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
{% endblock %}
{%- block js %}
{{ super() }}
{{ document.js|safe }}
{{ super() }}
{{ document.js|safe }}
{%- endblock %}
{%- block relbar %}
{{ document.relbar|safe }}
{{ document.relbar|safe }}
{%- endblock %}
{%- block body %}
{{ document.body|safe }}
{{ document.body|safe }}
{%- endblock %}
{%- block sidebar %}
{{ document.sidebar|safe }}
{{ document.sidebar|safe }}
{%- endblock %}
Authentication
@ -108,7 +108,7 @@ Once a user has been authenticated you can pass the user's details to certain
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::
support.update_username(old_username, new_username)
support.update_username(old_username, new_username)
*username* should be a unique string which identifies a user, and *moderator*
should be a boolean representing whether the user has moderation
@ -121,12 +121,12 @@ a user is logged in and then retrieves a document is::
@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)
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)
The first thing to notice is that the *docname* is just the request path.
@ -138,15 +138,15 @@ will then add this data to the COMMENT_OPTIONS that are used in the template.
.. note::
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 `docroot`
keyword argument when creating the web support object::
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 `docroot`
keyword argument when creating the web support object::
support = WebSupport(...
docroot='docs')
support = WebSupport(...
docroot='docs')
@app.route('/docs/<path:docname>')
@app.route('/docs/<path:docname>')
Performing Searches
~~~~~~~~~~~~~~~~~~~
@ -186,8 +186,8 @@ function is used to add a new comment, and will call the web support method
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)
parent_id='parent_id',
username=username, proposal=proposal)
return jsonify(comment=comment)
You'll notice that both a `parent_id` and `node_id` are sent with the
@ -200,8 +200,8 @@ specific node, and is aptly named
@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', '')
moderator = g.user.moderator if g.user else False
node_id = request.args.get('node', '')
data = support.get_data(parent_id, user_id)
return jsonify(**data)
@ -231,7 +231,7 @@ the `displayed` keyword argument::
comment = support.add_comment(text, node_id='node_id',
parent_id='parent_id',
username=username, proposal=proposal,
displayed=False)
displayed=False)
You can then create two new views to handle the moderation of comments. The
first will be called when a moderator decides a comment should be accepted
@ -240,18 +240,18 @@ and displayed::
@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'
comment_id = request.form.get('id')
support.accept_comment(comment_id, moderator=moderator)
return 'OK'
The next is very similar, but used when rejecting a comment::
@app.route('/docs/reject_comment', methods=['POST'])
def reject_comment():
moderator = g.user.moderator if g.user else False
comment_id = request.form.get('id')
support.reject_comment(comment_id, moderator=moderator)
return 'OK'
comment_id = request.form.get('id')
support.reject_comment(comment_id, moderator=moderator)
return 'OK'
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

21
doc/web/searchadapters.rst
View File

@ -10,26 +10,26 @@ To create a custom search adapter you will need to subclass the
and pass that as the `search` keyword argument when you create the
:class:`~sphinx.websupport.WebSupport` object::
support = Websupport(srcdir=srcdir,
builddir=builddir,
search=MySearch())
support = Websupport(srcdir=srcdir,
builddir=builddir,
search=MySearch())
For more information about creating a custom search adapter, please see
the documentation of the :class:`BaseSearch` class below.
.. class:: BaseSearch
Defines an interface for search adapters.
Defines an interface for search adapters.
BaseSearch Methods
~~~~~~~~~~~~~~~~~~
The following methods are defined in the BaseSearch class. Some methods
do not need to be overridden, but some (
:meth:`~sphinx.websupport.search.BaseSearch.add_document` and
:meth:`~sphinx.websupport.search.BaseSearch.handle_query`) must be
overridden in your subclass. For a working example, look at the
built-in adapter for whoosh.
The following methods are defined in the BaseSearch class. Some methods
do not need to be overridden, but some (
:meth:`~sphinx.websupport.search.BaseSearch.add_document` and
:meth:`~sphinx.websupport.search.BaseSearch.handle_query`) must be
overridden in your subclass. For a working example, look at the
built-in adapter for whoosh.
.. automethod:: sphinx.websupport.search.BaseSearch.init_indexing
@ -44,4 +44,3 @@ BaseSearch Methods
.. automethod:: sphinx.websupport.search.BaseSearch.handle_query
.. automethod:: sphinx.websupport.search.BaseSearch.extract_context

8
doc/web/storagebackends.rst
View File

@ -10,16 +10,16 @@ To create a custom storage backend you will need to subclass the
and pass that as the `storage` keyword argument when you create the
:class:`~sphinx.websupport.WebSupport` object::
support = Websupport(srcdir=srcdir,
builddir=builddir,
storage=MyStorage())
support = Websupport(srcdir=srcdir,
builddir=builddir,
storage=MyStorage())
For more information about creating a custom storage backend, please see
the documentation of the :class:`StorageBackend` class below.
.. class:: StorageBackend
Defines an interface for storage backends.
Defines an interface for storage backends.
StorageBackend Methods
~~~~~~~~~~~~~~~~~~~~~~

8
doc/websupport.rst
View File

@ -9,7 +9,7 @@ into your web application. To learn more read the
.. toctree::
web/quickstart
web/api
web/searchadapters
web/storagebackends
web/quickstart
web/api
web/searchadapters
web/storagebackends

1
sphinx/builders/websupport.py
View File

@ -148,4 +148,3 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
scripts.append(make_script(file))
scripts.append(make_script('_static/websupport.js'))
return opts + '\n' + '\n'.join(scripts)

1
sphinx/websupport/__init__.py
View File

@ -404,4 +404,3 @@ class WebSupport(object):
var COMMENT_METADATA = {%s};
</script>""" % node_js
return js

1
sphinx/websupport/search/__init__.py
View File

@ -119,4 +119,3 @@ search_adapters = {
'whoosh': ('whooshsearch', 'WhooshSearch'),
'null': ('nullsearch', 'NullSearch')
}

1
sphinx/websupport/storage/differ.py
View File

@ -76,4 +76,3 @@ class CombinedHtmlDiff(object):
start = match.end()
new_text.append(text[start:])
return ''.join(new_text)

1
tests/test_searchadapters.py
View File

@ -81,4 +81,3 @@ def test_whoosh():
except ImportError:
sys.stderr.write('info: not running whoosh tests, ' \
'whoosh doesn\'t seem to be installed')