.. _python_script_syntax:

=======================================================
How to structure your Python scripts for Sphinx-Gallery
=======================================================

This page describes the structure and syntax that can be used in Python scripts
to generate rendered HTML gallery pages.

A simple example
================

Sphinx-Gallery expects each Python file to have two things:

1. **A docstring**, written in rST, that defines the
   header for the example. It must begin by defining a rST title. The title
   may contain any punctuation mark but cannot start with the same punctuation
   mark repeated more than 3 times. For example::

    """
    "This" is my example-script
    ===========================

    This example doesn't do much, it just makes a simple plot
    """
2. **Python code**. This can be any valid Python code that you wish. Any
   Matplotlib images that are generated will be saved to disk, and
   the rST generated will display these images with the built examples. By
   default only images generated by Matplotlib, or packages based on Matplotlib
   (e.g., Seaborn or Yellowbrick) are saved and displayed. However, you can
   change this to include other packages, see :ref:`image_scrapers`.

For a quick reference have a look at the example
:ref:`sphx_glr_auto_examples_plot_0_sin.py`

.. _embedding_rst:

Embed rST in your example Python files
======================================

Additionally, you may embed rST syntax within your Python scripts. rST
allows you to easily add formatted text, math equations and reference links,
including :ref:`cross referencing other examples <cross_ref_example>`. This
will be rendered in-line with the Python code and its outputs, similar to how
Jupyter Notebooks are structured (in fact, Sphinx-Gallery also **creates** a
Jupyter Notebook for each example that is built).

You can embed rST in your Python examples by including a line of >= 20 ``#``
symbols, ``#%%``, or ``# %%``. For consistency, it is recommended that you use
only one of the above three 'block splitter' options in your project. If using
a line of ``#``'s, we recommend using 79 ``#``'s, like this::

  ###############################################################################

Any commented lines (line beginning with ``#`` followed by a space, to
be PEP8-compliant) that immediately follow a block splitter will be rendered as
rST in the built gallery examples. To switch back to writing code, either
stop starting lines with ``#`` and a space or leave an empty line before writing
code comments. You can thus easily alternate between text and code 'blocks'.
For example::

  # This is commented python
  myvariable = 2
  print("my variable is {}".format(myvariable))

  # %%
  # This is a section header
  # ------------------------
  #
  # In the built documentation, it will be rendered as rST. All rST lines
  # must begin with '# ' (note the space) including underlines below section
  # headers.

  # These lines won't be rendered as rST because there is a gap after the last
  # commented rST block. Instead, they'll resolve as regular Python comments.
  # Normal Python code can follow these comments.
  print('my variable plus 2 is {}'.format(myvariable + 2))

The ``#%%`` and ``# %%`` syntax is consistent with the 'code block' (or
'code cell') separator syntax in `Visual Studio Code Python extension
<https://code.visualstudio.com/docs/python/jupyter-support-py#_jupyter-code-cells>`_,
`Visual Studio Python Tools
<https://docs.microsoft.com/en-us/visualstudio/python/python-interactive-repl-in-visual-studio?view=vs-2019#work-with-code-cells>`_,
`Jupytext
<https://jupytext.readthedocs.io/en/latest/formats.html#the-percent-format>`_,
`Pycharm Professional
<https://www.jetbrains.com/help/pycharm/running-jupyter-notebook-cells.html>`_,
`Hydrogen plugin (for Atom)
<https://nteract.gitbooks.io/hydrogen/docs/Usage/Cells.html#example-definitions>`_
and `Spyder
<https://docs.spyder-ide.org/editor.html#defining-code-cells>`_.
Note that although the documentation of these editors/IDEs
may only mention one of ``#%%`` or ``# %%``, in practice both
work. With these editors/IDEs, ``#%%`` or
``# %%`` at the start of a line signifies the start of a new code block.
Code blocks allow you to separate your code into chunks, like in Jupyter
Notebooks. All the code within a code block can be easily executed together.
This functionality can be helpful when writing a Sphinx-Gallery ``.py``
example as
the blocks allow you to easily create pairs of subsequent Sphinx-Gallery text
and code blocks.

Here are the contents of an example Python file using the 'code block'
functionality::

  """
  This is my example script
  =========================

  This example doesn't do much, it just makes a simple plot
  """

  # %%
  # This is a section header
  # ------------------------
  # This is the first section!
  # The `#%%` signifies to Sphinx-Gallery that this text should be rendered as
  # rST and if using one of the above IDE/plugin's, also signifies the start of a
  # 'code block'.

  # This line won't be rendered as rST because there's a space after the last block.
  myvariable = 2
  print("my variable is {}".format(myvariable))
  # This is the end of the 'code block' (if using an above IDE). All code within
  # this block can be easily executed all at once.

  # %%
  # This is another section header
  # ------------------------------
  #
  # In the built documentation, it will be rendered as rST after the code above!
  # This is also another code block.

  print('my variable plus 2 is {}'.format(myvariable + 2))

For a clear example refer to the rendered example
:ref:`sphx_glr_tutorials_plot_parse.py` and compare it to the generated
:download:`original python script <tutorials/plot_parse.py>`
