Webサポートクイックスタート

建築文書データ

あなたのアプリケーションでWebサポートパッケージを使用するためには、使用するデータを構築する必要があります。これらのデータは、文書を表すPICLEファイル、検索インデックス、および文書内の注釈および他のコンテンツの位置を追跡するためのノードデータを含む。そのためには WebSupport クラスを呼び出して build() 方法：

from sphinxcontrib.websupport import WebSupport

support = WebSupport(srcdir='/path/to/rst/sources/',
                     builddir='/path/to/build/outdir',
                     search='xapian')

support.build()

これは srcdir 必要なデータを入れて builddir それがそうです。♪the builddir 2つのサブディレクトリを含む：“data”というディレクトリは，表示文書，検索文書，文書へのアノテーションに必要なすべてのデータを含む.別のディレクトリは、“/Static”から提供されるべき静的ファイルを含む“静的”と呼ばれる。

注釈

“/static”以外の経路から静的ファイルを提供したい場合は、提供することで 静態ディレクトリ キーワードパラメータ WebSupport 物体です。

SphinxドキュメントをWebアプリケーションに統合する

今はデータが構築されていて、それを使って何か有用なことをする時だ。まず最初に WebSupport アプリケーションのオブジェクト：：

from sphinxcontrib.websupport import WebSupport

support = WebSupport(datadir='/path/to/the/data',
                     search='xapian')

使用する各文書のセットについて、あなたはそのうちの1つだけが必要です。そして、それを呼び出すことができます get_document() 単一文書にアクセスする方法：

contents = support.get_document('contents')

これは、以下の項目を含む辞書を返す。

• body ：文書の本文はHTMLである.

• 側欄. ：文書のサイドバーはHTML

• 鉄筋 ：関連文書リンクを含むdiv

• タイトル ：文書のタイトル

• css ：Sphinxが使用するCSSファイルへのリンク

• スクリプト ：注釈オプションを含むJavaScript

そして、この辞書は、テンプレートの文脈として用いることができる。既存のテンプレート·システムとの統合を容易にすることを目標とする。以下のコマンドを用いた例 Jinja2 はい：

{%- 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 script %}
    {{ super() }}
    {{ document.script|safe }}
{%- endblock %}

{%- block relbar %}
    {{ document.relbar|safe }}
{%- endblock %}

{%- block body %}
    {{ document.body|safe }}
{%- endblock %}

{%- block sidebar %}
    {{ document.sidebar|safe }}
{%- endblock %}

認証

投票のような何らかの機能を利用するためには，ユーザの認証が可能でなければならない.認証の詳細はあなたのアプリケーションに残します。ユーザが認証を通過すると，ユーザの詳細な情報をユーザに伝えることができる. WebSupport 方法使用 ユーザー名 そして 司会者 キーワードパラメータ。Webサポートパッケージには、コメントや投票付きのユーザー名が格納されます。唯一注意すべきことは、ユーザがそのユーザ名を変更することを許可する場合、WebSupportパッケージのデータを更新しなければならないことです：

support.update_username(old_username, new_username)

ユーザー名 ユーザを識別する唯一の文字列であるべきであり 司会者 ユーザがレビュー権限を持つかどうかを示すブール値である.デフォルト値です。 司会者 はい。 False それがそうです。

例を挙げましょう Flask ユーザが登録しているかどうかをチェックし，文書を検索する関数は，

from sphinxcontrib.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)

まず注意しなければならないのは 文書名. 経路を要求するだけです。これにより、単一のビューから正しい文書にアクセスすることが容易になる。ユーザが認証を通過した場合、ユーザ名およびレビュー状態は、文書名と共に転送される get_document() それがそうです。そして，Webサポートパッケージはこのデータを追加する. COMMENT_OPTIONS テンプレートに使用されています。

注釈

これは、あなたの文書が文書ルートディレクトリから提供される場合にのみ有効です。別のディレクトリから提供される場合、urlルーティングにディレクトリのプレフィックスを追加し、与える必要がある。 docroot Webサポートオブジェクトを作成する際のキーワードパラメータ：：

support = WebSupport(..., docroot='docs')

@app.route('/docs/<path:docname>')

捜索を実行する

Sphinxサイドバーに内蔵されている検索フォームを使用するには、文書ルートディレクトリに対するURL“search”の要求を処理する関数を作成してください。ユーザの検索クエリはGETパラメータに位置し，キーは q. Then use the get_search_results() method to retrieve search results. In Flask このようなものであるはずだ。

@app.route('/search')
def search():
    q = request.args.get('q')
    document = support.get_search_results(q)
    return render_template('doc.html', document=document)

なお、提示文書と同じテンプレートを用いて検索結果を提示する。それは…。 get_search_results() コンテキスト辞書を返し、そのフォーマットと get_document() その通りです。

コメントと提案

現在はこの作業が完了しており，現在では処理スクリプト中のAjaxが呼び出す関数を定義することができる.あなたは三つの関数が必要です。最初の関数は、新しいコメントを追加し、Webサポート方法を呼び出すために使用されます。 add_comment() **

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

ご覧のように2つは parent_id そして node_id 要求と一緒に送ります。コメントが直接ノードに付加されていれば parent_id 全部空になります。そのコメントが別のコメントのサブレベルである場合、 node_id 全部空になります。そして，Next関数は特定のノードのアノテーション検索を処理し，これを名前付けする. get_data() **

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

必要な最後の関数は呼び出されます process_vote() そして、コメントに対するユーザの投票を処理する：

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

レビュー審査

デフォルトの場合、すべての通過は add_comment() 自動的に表示されます。もし何らかの形の節制を望むなら、あなたは通過することができます displayed キーワードパラメータ：：

comment = support.add_comment(text, node_id='node_id',
                              parent_id='parent_id',
                              username=username, proposal=proposal,
                              displayed=False)

そして、レビューのレビューを処理するための新しいビューを作成することができます。これは、著作権者がコメントを受け入れて表示することを決定したときに呼び出されます。

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

論評を拒否することは論評を削除することによって達成される。

新たなコメントを追加して表示されていない場合にカスタマイズ操作(たとえば版主に電子メールを送信する)を実行するには，Callableを転送することができる. WebSupport インスタンス化サポートオブジェクトの場合初期化：：

def moderation_callback(comment):
    """Do something..."""

support = WebSupport(..., moderation_callback=moderation_callback)

レビューコールバックは、返された注釈辞書と同じパラメータを受け入れなければならない add_comment() それがそうです。