WebSupportクラス

class sphinxcontrib.websupport.WebSupport[ソース]

ウェブサポートパッケージのメインとなるAPIクラスです。ウェブサポートパッケージに対して行われる、すべてのインタラクションは、このクラスを通じて行われます。

このクラスは、次のようなキーワード引数を取ります:

srcdir

reStructuredTextのソースファイルを含むディレクトリです。

builddir

ビルド済みのデータや、静的ファイルを置くべきディレクトリです。これはデータをビルドする WebSupport オブジェクトを作る時に使用されます。

datadir

ウェブサポートのデータが置かれるディレクトリです。このデータを読み込む 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()

これにより srcdir よりreStructuredテキストファイルが読み込まれます。ピクルがビルドされ、インデックスを検索し、 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` が見つからない場合は、 :class:`~sphinxcontrib.websupport.errors.DocumentNotFoundError`が発生します。

パラメータ:

docname -- ロードするドキュメントの名前。

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

コメントとソースを node_id に関連付けます。 username が与えられた場合、返されるコメントには投票情報が含まれます。デフォルトの CommentBackend は source と comments の2つのキーを持つ辞書を返します。 source はノードの生のソースで、ユーザが追加できる提案の開始点として使用されます。 comments は、コメントを表わす辞書のリストです。各々は以下のアイテムを持ちます:

Key

目次

text

コメント文。

username

コメントとともに保存されるユーザ名。

id

コメントのユニークな識別子。

rating

コメントの現在の評価。

age

コメントが追加されてからの秒数。

time

時刻情報を含む辞書。それは次のキーを含んでいます: year, month, day, hour, minute, second, iso, and delta 。 iso は ISO 8601 形式でフォーマットされた時刻です。 delta はコメントがどれくらい古いかの表示可能な形式 (例えば "3 hours ago") です。

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 -- コメントの親のprefixがついたID。

  • text -- コメントの文字列。

  • displayed -- モデレーションのため

  • username -- コメントを作成しているユーザーのユーザー名。

  • time -- コメントが作成された時刻。デフォルトは現在時間。

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

ユーザの投票を処理します。ウェブサポートパッケージは認証を行なうために API ユーザに依存します。 API ユーザは、典型的にはフォームから comment_id と値を受け取り、次にユーザが認証されることを確かめます。ユニークなユーザ名が渡される必要があります。さらに、それはユーザが過去に投票したデータを検索するためにも使用されます。もう一度 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 -- 検索クエリー