テキストとコードの交互表示

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