WebSupport クラス¶

class sphinxcontrib.websupport.WebSupport[ソース]¶

Web サポートパッケージのメイン API クラスです。Web サポートパッケージとのすべてのやり取りは、このクラスを通じて行われる必要があります。

このクラスは、次のキーワード引数を取ります。

srcdir: reStructuredText ソースファイルを含むディレクトリ。
builddir: ビルドデータと静的ファイルを配置するディレクトリ。これは、データをビルドするために使用される WebSupport オブジェクトを作成するときに使用する必要があります。
datadir: Web サポートデータがあるディレクトリ。これは、データを取得するために使用される WebSupport オブジェクトを作成するときに使用する必要があります。
search: これは、使用する組み込み検索アダプタを参照する文字列（例：'xapian'）、または BaseSearch のサブクラスのインスタンスのいずれかを含めることができます。
storage: これは、データベース URI を表す文字列、または StorageBackend のサブクラスのインスタンスのいずれかを含めることができます。これが指定されていない場合は、新しい sqlite データベースが作成されます。
moderation_callback: 表示されない新しいコメントが追加されたときに呼び出されるコールバック関数。1 つの引数（追加されたコメントを表す辞書）を受け入れる必要があります。
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()[ソース]¶

ドキュメントをビルドします。データを outdir ディレクトリに配置します。次のように使用します。

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

これにより、reStructured Text ファイルが srcdir から読み込まれます。次に、pickle と検索インデックスをビルドし、それらを builddir に配置します。また、ノードデータをデータベースに保存します。

WebSupport.get_document(docname, username='', moderator=False)[ソース]¶

pickle からドキュメントをロードして返します。ドキュメントは、テンプレートのレンダリングに使用できる辞書オブジェクトになります。

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

ほとんどの場合、docname はリクエストパスから取得され、この関数に直接渡されます。Flask では、次のようになります。

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

返されるドキュメント辞書には、テンプレートレンダリング中に使用される次の項目が含まれています。

body: ドキュメントのメインボディ（HTML）
sidebar: ドキュメントのサイドバー（HTML）
relbar: 関連ドキュメントへのリンクを含む div
title: ドキュメントのタイトル
css: Sphinx が使用する CSS ファイルへのリンク
script: コメントオプションを含む Javascript

docname に一致するドキュメントが見つからない場合は、DocumentNotFoundError が発生します。

パラメーター:: docname – ロードするドキュメントの名前。

WebSupport.get_data(node_id, username=None, moderator=False)[ソース]¶

node_id に関連付けられたコメントとソースを取得します。username が指定されている場合は、返されたコメントに投票情報が含まれます。デフォルトの CommentBackend は、source と comments の 2 つのキーを持つ辞書を返します。source はノードの生のソースであり、ユーザーが追加できる提案の開始点として使用されます。comments は、コメントを表す辞書のリストであり、それぞれに次の項目があります。

キー	内容
text	コメントテキスト。
username	コメントとともに保存されたユーザー名。
id	コメントの一意の識別子。
rating	コメントの現在の評価。
age	コメントが追加されてからの秒数。
time	時間情報を含む辞書。year、month、day、hour、minute、second、iso、delta のキーが含まれています。iso は ISO 8601 形式でフォーマットされた時間です。delta は、コメントがどれくらい古いかを示す印刷可能な形式です（例：「3時間前」）。
vote	user_id が指定された場合、これは投票を表す整数になります。賛成票は 1、反対票は -1、投票されていない場合は 0 になります。
node	コメントが添付されているノードの ID。コメントの親がノードではなく別のコメントである場合、これは null になります。
parent	ノードに添付されていない場合、このコメントが添付されているコメントの ID。
children	この形式のすべての子のリスト。
proposal_diff	現在のソースとユーザーが提案したソースの間の差分の HTML 表現。

パラメーター:

node_id – コメントを取得するノードの ID。
username – コメントを表示しているユーザーのユーザー名。
moderator – ユーザーがモデレーターかどうか。

WebSupport.add_comment(text, node_id='', parent_id='', displayed=True, username=None, time=None, proposal=None, moderator=False)[ソース]¶

コメントをノードまたは別のコメントに追加します。get_comments() と同じ形式でコメントを返します。コメントをノードに添付する場合は、node キーワード引数を使用してノードの ID（文字列として）を渡します。

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

コメントが別のコメントの子である場合は、parent キーワード引数を使用して親の ID（文字列として）を指定します。

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

コメントとともにユーザー名を保存する場合は、オプションの username キーワード引数を渡します。

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

パラメーター:

parent_id – コメントの親のプレフィックス付き ID。
text – コメントのテキスト。
displayed – モデレーション用。
username – コメントを作成しているユーザーのユーザー名。
time – コメントが作成された時間。デフォルトは現在。

WebSupport.process_vote(comment_id, username, value)[ソース]¶

ユーザーの投票を処理します。Webサポートパッケージは、認証を実行するためにAPIユーザーに依存しています。APIユーザーは通常、フォームからcomment_idとvalueを受け取り、その後、ユーザーが認証されていることを確認します。ユニークなユーザー名が渡される必要があり、これはユーザーの過去の投票データを取得するためにも使用されます。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 – 投票されているコメント
username – 投票するユーザーの一意のユーザー名
value – 賛成票の場合は1、反対票の場合は-1、投票を取り消す場合は0。

WebSupport.get_search_results(q)[ソース]¶

クエリ q の検索を実行し、検索結果のセットを作成します。次に、検索結果をhtmlとしてレンダリングし、get_document() によって作成されたものと同様のコンテキスト辞書を返します。

document = support.get_search_results(q)

パラメーター:: q – 検索クエリ