WebSupportクラス

class sphinx.websupport.WebSupport[ソース]

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

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

srcdir
reStructuredTextのソースファイルを含むディレクトリです。
builddir
ビルド済みのデータや、静的ファイルを置くべきディレクトリです。これはデータをビルドする WebSupport オブジェクトを作る時に使用されます。
datadir
ウェブサポートのデータが置かれるディレクトリです。このデータを読み込む WebSupport オブジェクトが作成されるときに使用されます。
search
これは組み込みの検索アダプタを参照するための文字列(例: ‘xapian’)か、 BaseSearch クラスのサブクラスのインスタンスを指定します。
storage
これはデータベースのURIを表す文字列、もしくは StorageBackend のサブクラスのインスタンスを指定します。もしどちらも指定されなかった場合には、新しいsqliteデータベースが作られます。
moderation_callback
非表示の新しいコメントが追加されたときに呼び出されるコールバックです。この関数には、追加されたコメントを表す引数が1つ渡されます。
staticdir
静的ファイルが提供される場所が、 '/static' 以外の場合には、その場所の名前を表す文字列(例: '/static_files')を指定します。
docroot
ドキュメントがURLのベースパスから送信されない場合には、そのパスを表す文字(例: 'docs')を指定します。

メソッド

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 とマッチするドキュメントが見つからない場合、この関数は DocumentNotFoundError を送出します。

パラメータ:docname – ロードするドキュメントの名前。
WebSupport.get_data(node_id, username=None, moderator=False)[ソース]

コメントとソースを node_id に関連付けます。 username が与えられた場合、返されるコメントには投票情報が含まれます。デフォルトの CommentBackend は sourcecomments の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 – 検索クエリー