Note

Go to the endto download the full example code or to run this example in your browser via JupyterLite or Binder.

Alternating text and code#

Sphinx-Gallery is capable of transforming Python files into reST fileswith a notebook structure. For this to be used you need to respect some syntaxrules. This example demonstrates how to alternate text and code blocks and someedge cases. It was designed to be compared with thesourcePythonscript.

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

importnumpyasnp# 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=1importmatplotlib.pyplotasplt# noqa: F401

Block splitters allow you alternate between code and text blocksandseparate sequential blocks of code (above) and text (below).

A line of#’s also works for separating blocks. The above line of#’sseparates the text block above from this text block. Notice however, thatseparated text blocks only shows as a new lines between text, in the renderedoutput.

defdummy():"""This should not be part of a 'text' block'"""# noqa: D404# %%# This comment inside a code block will remain in the code blockpass# 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#’sand the#%% start at the margin instead of being indented likeabove) and become too hard to escape so just don’t use code like this:

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

"""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'

New lines can be included in your text block and the parseris 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 textblock together using# and a space at the beginning of each line.

reST header within text block#

print("one")

one

# another way to separate code blocks shown aboveB=1

Code blocks containing Jupyter magic are executable

%%bash# This could be run!

Last text block.

That’s all folks !

"""Alternating text and code=========================Sphinx-Gallery is capable of transforming Python files into reST fileswith a notebook structure. For this to be used you need to respect some syntaxrules. This example demonstrates how to alternate text and code blocks and someedge 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.importnumpyasnp# 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=1importmatplotlib.pyplotasplt# 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.defdummy():"""This should not be part of a 'text' block'"""# noqa: D404# %%# This comment inside a code block will remain in the code blockpass# 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 aboveB=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##