sphinx_gallery.gen_rst#
reST 檔案產生器。
藉由迭代 Python 範例檔案來產生範例的 rst 檔案。
產生圖片的檔案應以「plot」開頭。
函式#
- sphinx_gallery.gen_rst.codestr2rst(codestr, lang='python', lineno=None)[原始碼]#
從程式碼字串傳回 reStructuredText 程式碼區塊。
- sphinx_gallery.gen_rst.executable_script(src_file, gallery_conf)[原始碼]#
根據圖庫設定驗證腳本是否需要執行。
- 參數:
src_file (str) – Python 腳本的路徑
gallery_conf (dict) – 包含 Sphinx-Gallery 的設定
- 傳回:
若腳本需要執行則為 True
- 傳回類型:
- sphinx_gallery.gen_rst.execute_code_block(compiler, block, example_globals, script_vars, gallery_conf, file_conf)[原始碼]#
執行範例檔案的程式碼區塊。
- 參數:
compiler (codeop.Compile) – 用於編譯程式碼區塊 AST 的編譯器。
block (sphinx_gallery.py_source_parser.Block) – 要執行的程式碼區塊。
example_globals (Dict[str, Any]) – 範例的全域變數。
script_vars (Dict[str, Any]) – 設定和執行階段變數。
gallery_conf (Dict[str, Any]) – 圖庫設定。
file_conf (Dict[str, Any]) – 在原始碼檔案註解中給定的檔案特定設定，格式為：
# sphinx_gallery_<name> = <value>。
- 傳回:
code_output – 以 reST 格式執行的程式碼輸出。
- 傳回類型:
- sphinx_gallery.gen_rst.execute_script(script_blocks, script_vars, gallery_conf, file_conf)[原始碼]#
執行並擷取已在區塊結構中的 Python 腳本的輸出。
- 參數:
script_blocks (list) – (標籤、內容、行號) 列表，其中每個元素是一個元組，包含標籤（「文字」或「程式碼」）、區塊的對應內容字串和起始行號
script_vars (dict) – 設定和執行階段變數
gallery_conf (dict) – 包含 Sphinx-Gallery 的設定
file_conf (dict) – 在原始碼檔案註解中給定的檔案特定設定，格式為：
# sphinx_gallery_<name> = <value>
- 傳回:
output_blocks (list) – 字串列表，其中每個元素是每個區塊輸出的重組文字表示
time_elapsed (float) – 執行期間經過的時間
- sphinx_gallery.gen_rst.extract_intro_and_title(filename, docstring)[原始碼]#
擷取並清理模組層級 docstring 的第一個段落。
- sphinx_gallery.gen_rst.generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs, is_subsection=True)[原始碼]#
為範例目錄產生圖庫的 reStructuredText。
- 參數:
src_dir (str,) – 包含範例檔案的根目錄或子圖庫目錄的路徑
target_dir (str,) – 已剖析的範例 (rst、Python 檔案等) 將輸出的路徑
gallery_conf (Dict[str, Any]) – 圖庫設定。
seen_backrefs (set,) – 剖析此圖庫時遇到的反向參照將儲存在此集中。
is_subsection (bool,) – src_dir 是否為子章節目錄。如果是子章節目錄，我們會寫入一個 index.rst 檔案，其中包含列出每個範例檔案的 toctree。預設值 = True。
- 傳回:
index_path (str or None) – src_dir 的索引 rst 檔案的路徑。如果使用者提供自己的索引，則為 None。
index_content (str or None) – 圖庫標頭內容。當使用者提供自己的 index.rst 時為 None。
costs (List[Dict]) –
- 用於建立圖庫每個元素的成本字典列表，
包含鍵「t」、「mem」、「src_file」和「target_dir」。
toctree_items (list,) – 我們產生 ReST 的範例檔案名稱列表。
- sphinx_gallery.gen_rst.generate_file_rst(fname, target_dir, src_dir, gallery_conf)[原始碼]#
為給定的範例產生 rst 檔案。
- 參數:
fname (str) – Python 腳本的檔案名稱。
target_dir (str) – 文件中儲存範例的目錄的絕對路徑。
src_dir (str) – 儲存來源範例的目錄的絕對路徑。
gallery_conf (dict) – 包含 Sphinx-Gallery 的設定。
- 傳回:
intro (str) – 範例的簡介。
title (str) – 範例標題。
cost (tuple) – 一個元組，包含執行腳本所需的
(time_elapsed, memory_used)。out_vars (dict) – 用於執行腳本的變數，可能具有以下項目
- 「stale」
如果範例已過時，則為 True。
- 「backrefs」
反向參照。
- 「passing」
如果範例通過，則為 True。
- 「formatted_exception」
已格式化的例外狀況字串。
- sphinx_gallery.gen_rst.handle_exception(exc_info, src_file, script_vars, gallery_conf)[原始碼]#
修剪並格式化例外狀況，可能引發錯誤等。
- sphinx_gallery.gen_rst.rst_blocks(script_blocks, output_blocks, file_conf, gallery_conf, *, language='python')[原始碼]#
產生包含腳本散文、程式碼和輸出的 rst 字串。
- 參數:
script_blocks (list) – (標籤、內容、行號) 列表，其中每個元素是一個元組，包含標籤（「文字」或「程式碼」）、區塊的對應內容字串和起始行號
output_blocks (清單) – 字串清單，其中每個元素都是每個區塊輸出的 reStructuredText 表示法
file_conf (dict) – 在原始碼檔案註解中給定的檔案特定設定，格式為：
# sphinx_gallery_<name> = <value>language (字串) – 用於程式碼區塊語法突顯的語言。必須是 Pygments 可辨識的名稱或別名。
gallery_conf (dict) – 包含 Sphinx-Gallery 的設定
- 傳回:
out – rst 筆記本
- 傳回類型:
- sphinx_gallery.gen_rst.save_rst_example(example_rst, example_file, time_elapsed, memory_used, gallery_conf, *, language='python')[原始碼]#
將 rst 筆記本（包含標頭和頁尾）儲存到 example_file。