文字與程式碼交錯

Sphinx-Gallery 能夠將 Python 檔案轉換為具有筆記本結構的 reST 檔案。若要使用此功能，您需要遵守一些語法規則。此範例示範如何交替使用文字和程式碼區塊，以及一些邊緣情況。它被設計為與來源 Python 腳本進行比較。

這是第一個文字區塊，直接接在上面的標頭 docstring 之後。

import numpy as np  # noqa: F401

# You can separate code blocks using either a single line of ``#``'s
# (>=20 columns), ``#%%``, or ``# %%``. For consistency, it is recommend that
# you use only one of the above three 'block splitter' options in your project.
A = 1

import matplotlib.pyplot as plt  # noqa: F401

區塊分隔符允許您在程式碼和文字區塊之間交替，並分隔循序的程式碼區塊（上方）和文字區塊（下方）。

一行 # 也可用於分隔區塊。上面那行 # 將上面的文字區塊與這個文字區塊分隔開來。但是請注意，分隔的文字區塊在呈現的輸出中僅顯示為文字之間的新行。

def dummy():
    """This should not be part of a 'text' block'"""  # noqa: D404

    # %%
    # This comment inside a code block will remain in the code block
    pass


# this line should not be part of a 'text' block

---

上面的語法會在 Sphinx 中產生換行。請注意第一個 # 和 # 行之間的空格。

警告

不支援下一種註解（請注意，# 行和 # %% 從邊界開始，而不是像上面一樣縮排），並且變得太難以跳脫，所以請不要使用這樣的程式碼

def dummy2():
    """Function docstring"""
####################################
# This comment
# %%
# and this comment inside python indentation
# breaks the block structure and is not
# supported
    dummy2

"""Free strings are not supported. They will be rendered as a code block"""

'Free strings are not supported. They will be rendered as a code block'

新行可以包含在您的文字區塊中，並且解析器能夠保留此重要的空白，以便與 Sphinx 協同工作。在區塊分隔符之後，以 # 開頭，然後是一個空格的所有內容，都會被 Sphinx-Gallery 解釋為 reST 文字區塊。使用 # 和每行開頭的空格，將文字區塊保持在一起。

文字區塊內的 reST 標頭

print("one")

one

# another way to separate code blocks shown above
B = 1

包含 Jupyter magic 的程式碼區塊是可執行的

%%bash
# This could be run!

最後一個文字區塊。

就這樣啦！

"""
Alternating text and code
=========================

Sphinx-Gallery is capable of transforming Python files into reST files
with a notebook structure. For this to be used you need to respect some syntax
rules. This example demonstrates how to alternate text and code blocks and some
edge cases. It was designed to be compared with the
:download:`source Python script <plot_parse.py>`."""

# %%
# This is the first text block and directly follows the header docstring above.

import numpy as np  # noqa: F401

# %%

# You can separate code blocks using either a single line of ``#``'s
# (>=20 columns), ``#%%``, or ``# %%``. For consistency, it is recommend that
# you use only one of the above three 'block splitter' options in your project.
A = 1

import matplotlib.pyplot as plt  # noqa: F401

# %%
# Block splitters allow you alternate between code and text blocks **and**
# separate sequential blocks of code (above) and text (below).

##############################################################################
# A line of ``#``'s also works for separating blocks. The above line of ``#``'s
# separates the text block above from this text block. Notice however, that
# separated text blocks only shows as a new lines between text, in the rendered
# output.


def dummy():
    """This should not be part of a 'text' block'"""  # noqa: D404

    # %%
    # This comment inside a code block will remain in the code block
    pass


# this line should not be part of a 'text' block

# %%
#
# ####################################################################
#
# The above syntax makes a line cut in Sphinx. Note the space between the first
# ``#`` and the line of ``#``'s.

# %%
# .. warning::
#     The next kind of comments are not supported (notice the line of ``#``'s
#     and the ``# %%`` start at the margin instead of being indented like
#     above) and become too hard to escape so just don't use code like this::
#
#         def dummy2():
#             """Function docstring"""
#         ####################################
#         # This comment
#         # %%
#         # and this comment inside python indentation
#         # breaks the block structure and is not
#         # supported
#             dummy2
#

"""Free strings are not supported. They will be rendered as a code block"""

# %%
# New lines can be included in your text block and the parser
# is capable of retaining this important whitespace to work with Sphinx.
# Everything after a block splitter and starting with ``#`` then one space,
# is interpreted by Sphinx-Gallery to be a reST text block. Keep your text
# block together using ``#`` and a space at the beginning of each line.
#
# reST header within text block
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

print("one")

# %%
#

# another way to separate code blocks shown above
B = 1

# %%
# Code blocks containing Jupyter magic are executable
#     .. code-block:: bash
#
#       %%bash
#       # This could be run!
#

# %%
# Last text block.
#
# That's all folks !
#
# .. literalinclude:: plot_parse.py
#
#

估計記憶體使用量： 176 MB