WebSupport 類別¶

class sphinxcontrib.websupport.WebSupport[原始碼]¶

用於網路支援套件的主要 API 類別。所有與網路支援套件的互動都應透過此類別進行。

此類別接受以下關鍵字引數

srcdir: 包含 reStructuredText 原始檔的目錄。
builddir: 應放置建置資料和靜態檔案的目錄。在建立將用於建置資料的 WebSupport 物件時，應使用此目錄。
datadir: 網路支援資料所在的目錄。在建立將用於檢索資料的 WebSupport 物件時，應使用此目錄。
search: 這可以包含字串（例如 'xapian'），參考要使用的內建搜尋配接器，或 BaseSearch 子類別的實例。
storage: 這可以包含代表資料庫 URI 的字串，或 StorageBackend 子類別的實例。如果未提供，將建立新的 sqlite 資料庫。
moderation_callback: 新增未顯示的註解時要呼叫的可呼叫物件。它必須接受一個引數：代表新增的註解的字典。
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 text 檔案。然後它將建置 pickles 和搜尋索引，將它們放入 builddir。它還會將節點資料儲存到資料庫。

WebSupport.get_document(docname, username='', moderator=False)[原始碼]¶

從 pickle 載入並傳回文件。文件將是一個 dict 物件，可用於呈現範本

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)

傳回的文件 dict 包含以下項目，用於範本呈現期間。

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 傳回具有兩個鍵的 dict，source 和 comments。source 是節點的原始碼，用作使用者可以新增建議的起點。comments 是 dict 的列表，代表一個註解，每個 dict 具有以下項目

鍵	內容
text	註解文字。
username	與註解一起儲存的使用者名稱。
id	註解的唯一識別碼。
rating	註解目前的評分。
age	自新增註解以來經過的時間（以秒為單位）。
time	包含時間資訊的 dict。它包含以下鍵：年、月、日、時、分、秒、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)[原始碼]¶

處理使用者的投票。網路支援套件依賴 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() 建立的內容 dict

document = support.get_search_results(q)

參數:: q – 搜尋查詢