交替文本和代码

Sphinx-Gallery 能够将 Python 文件转换为具有笔记本结构的 reST 文件。要使用此功能，您需要遵循一些语法规则。此示例演示了如何交替文本和代码块，以及一些边缘情况。它的设计是为了与 源 Python 脚本 进行比较。

这是第一个文本块，它紧随上面的标题文档字符串。

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 魔术的代码块是可执行的

%%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