Repository: sphinx-gallery/sphinx-gallery

Issue:
Mention the multiple possible separators in the notebook-style example
The example on notebook-style should refer to the talk to mention that multiple separators are possible:
https://sphinx-gallery.github.io/stable/tutorials/plot_parse.html#sphx-glr-tutorials-plot-parse-py

Maybe we should have another example for the file with separators that is compatible with atom / vscode. It help users find this feature.

Discussion:
codecov-io: # [Codecov](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615?src=pr&el=h1) Report
> Merging [#615](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615?src=pr&el=desc) into [master](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/commit/56fa28c9f147a3d4c7391591b7b5916e6470a9c6?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615/graphs/tree.svg?width=650&token=K4eytvhwU5&height=150&src=pr)](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master     #615      +/-   ##
==========================================
+ Coverage   97.67%   97.68%   +<.01%     
==========================================
  Files          31       31              
  Lines        3137     3147      +10     
==========================================
+ Hits         3064     3074      +10     
  Misses         73       73
```


| [Impacted Files](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [sphinx\_gallery/gen\_gallery.py](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615/diff?src=pr&el=tree#diff-c3BoaW54X2dhbGxlcnkvZ2VuX2dhbGxlcnkucHk=) | `96.07% <0%> (ø)` | :arrow_up: |
| [sphinx\_gallery/tests/test\_gen\_rst.py](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615/diff?src=pr&el=tree#diff-c3BoaW54X2dhbGxlcnkvdGVzdHMvdGVzdF9nZW5fcnN0LnB5) | `99.12% <0%> (+0.01%)` | :arrow_up: |
| [sphinx\_gallery/gen\_rst.py](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615/diff?src=pr&el=tree#diff-c3BoaW54X2dhbGxlcnkvZ2VuX3JzdC5weQ==) | `97.97% <0%> (+0.01%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615?src=pr&el=footer). Last update [56fa28c...21d3254](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/615?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

lucyleeow: Thanks @GaelVaroquaux, merging

Patch:
diff --git a/doc/syntax.rst b/doc/syntax.rst
index ccef82c..4ba243d 100644
--- a/doc/syntax.rst
+++ b/doc/syntax.rst
@@ -43,16 +43,16 @@ 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 ``#`` 
+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 options in your project. If using ``#``'s, we
-recommend using 79 ``#``'s, like this::
+only one of the above three 'block splitter' options in your project. If using
+``#``'s, we recommend using 79 ``#``'s, like this::
 
   ###############################################################################
 
-Any commented lines (a line beginning with ``#`` and a space so they are
-PEP8-compliant) that immediately follow will be rendered as rST in the built
-gallery examples. For example::
+Any commented lines (a 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. For example::
 
   # This is commented python
   myvariable = 2
@@ -68,19 +68,23 @@ gallery examples. For example::
   # commented rST block. Instead, they'll resolve as regular Python comments.
   print('my variable plus 2 is {}'.format(myvariable + 2))
 
-The ``#%%`` syntax is consistent with the 'code block' (or 'code cell')
-syntax in `Jupyter VSCode plugin
-<https://code.visualstudio.com/docs/python/jupyter-support>`_, `Jupytext
+The ``#%%`` and ``# %%`` syntax is consistent with the 'code block' (or
+'code cell') separator syntax in `Jupyter VSCode plugin
+<https://code.visualstudio.com/docs/python/jupyter-support-py>`_, `Jupytext
 <https://jupytext.readthedocs.io/en/latest/introduction.html>`_, `Pycharm
-<https://www.jetbrains.com/help/pycharm/running-jupyter-notebook-cells.html>`_, 
+<https://www.jetbrains.com/help/pycharm/running-jupyter-notebook-cells.html>`_,
 `Hydrogen plugin (for Atom)
 <https://nteract.gitbooks.io/hydrogen/>`_ and `Spyder
-<https://docs.spyder-ide.org/editor.html>`_. In these IDEs/with these IDE 
-plugins, ``#%%`` at the start of a line signifies the start of a code block. 
-The code within a code block can be easily executed all at once. This 
-functionality can be helpful when writing a Sphinx-Gallery ``.py`` script.
-
-Here are the contents of an example Python file using the 'code block' 
+<https://docs.spyder-ide.org/editor.html>`_. Note that although the
+documentation may only mention one of ``#%%`` or ``# %%``, in practice both
+work in these editors. In these IDEs (or with these IDE plugins), ``#%%`` or
+``# %%`` at the start of a line signifies the start of a new code block.
+Code within a code block can be easily executed together, at the same time. 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::
 
   """
@@ -95,7 +99,7 @@ functionality::
   # ------------------------
   # 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 
+  # 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.
diff --git a/tutorials/plot_parse.py b/tutorials/plot_parse.py
index 36c6e2c..a4ad511 100644
--- a/tutorials/plot_parse.py
+++ b/tutorials/plot_parse.py
@@ -10,28 +10,28 @@ 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
 
-##################################################
+# %%
 
-# a block separator (line of #'s) allows you to create two separate code blocks
+# 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
 
-#####################################
-# You can easily alternate between code and text blocks **and** separate
-# sequential blocks of code (above) and text (below). Note that separated
-# text blocks only shows as a new lines between text, in the rendered output.
+# %%
+# Block splitters allow you alternate between code and text blocks **and**
+# separate sequential blocks of code (above) and text (below). Note that
+# separated text blocks only shows as a new lines between text, in the rendered
+# output.
 
-#############################################
-# You can separate 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 options in your project. All future 'block splitters' used
-# in the sphinx-gallery source ``.py`` documents will be ``#%%``.
+##############################################################################
+# A line of ``#``'s also works for separating blocks (above).
 
 def dummy():
     """This should not be part of a 'text' block'"""
@@ -42,14 +42,14 @@ def dummy():
 
 # this 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 and become too hard to escape
 #     so just don't code like this::
@@ -57,7 +57,7 @@ def dummy():
 #         def dummy2():
 #             """Function docstring"""
 #         ####################################
-#         # This comment 
+#         # This comment
 #         #%%
 #         # and this comment inside python indentation
 #         # breaks the block structure and is not
@@ -67,7 +67,7 @@ def dummy():
 
 """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,
@@ -79,13 +79,13 @@ def dummy():
 
 print('one')
 
-#%%
+# %%
 #
 
 # another way to separate code blocks shown above
 B = 1
 
-#%%
+# %%
 # Last text block.
 #
 # That's all folks !


Test patch:
diff --git a/sphinx_gallery/tests/reference_parse.txt b/sphinx_gallery/tests/reference_parse.txt
index 76c3b04..870df72 100644
--- a/sphinx_gallery/tests/reference_parse.txt
+++ b/sphinx_gallery/tests/reference_parse.txt
@@ -11,36 +11,32 @@
   'edge cases. It was designed to be compared with the\n'
   ':download:`source Python script <plot_parse.py>`.',
   1),
- ('text',
+('text',
   'This is the first text block and directly follows the header docstring '
   'above.\n',
   14),
- ('code', '\nimport numpy as np\n\n', 15),
- ('code',
+('code', '\nimport numpy as np\n\n', 15),
+('code',
   '\n'
-  "# a block separator (line of #'s) allows you to create two separate code "
-  'blocks\n'
+  "# You can separate code blocks using either a single line of ``#``'s\n"
+  '# (>=20 columns), ``#%%``, or ``# %%``. For consistency, it is recommend '
+  'that\n'
+  "# you use only one of the above three 'block splitter' options in your "
+  'project.\n'
   'A = 1\n'
   '\n'
   'import matplotlib.pyplot as plt\n'
   '\n',
   19),
- ('text',
-  'You can easily alternate between code and text blocks **and** separate\n'
-  'sequential blocks of code (above) and text (below). Note that separated\n'
-  'text blocks only shows as a new lines between text, in the rendered '
+('text',
+  'Block splitters allow you alternate between code and text blocks **and**\n'
+  'separate sequential blocks of code (above) and text (below). Note that\n'
+  'separated text blocks only shows as a new lines between text, in the '
+  'rendered\n'
   'output.\n',
-  26),
- ('text',
-  "You can separate blocks using either a single line of ``#``'s (>=20 "
-  'columns),\n'
-  '``#%%``, or ``# %%``. For consistency, it is recommend that you use '
-  'only one\n'
-  "of the above three options in your project. All future 'block "
-  "splitters' used\n"
-  "in the sphinx-gallery source ``.py`` documents will be ``#%%``.\n",
-  31),
- ('code',
+  28),
+('text', "A line of ``#``'s also works for separating blocks (above).\n", 34),
+('code',
   '\n'
   'def dummy():\n'
   '    """This should not be part of a \'text\' block\'"""\n'
@@ -52,14 +48,14 @@
   "# this should not be part of a 'text' block\n"
   '\n',
   35),
- ('text',
+('text',
   '####################################################################\n'
   '\n'
   'The above syntax makes a line cut in Sphinx. Note the space between the '
   'first\n'
   "``#`` and the line of ``#``'s.\n",
   46),
- ('text',
+('text',
   '.. warning::\n'
   '    The next kind of comments are not supported and become too hard to '
   'escape\n'
@@ -68,7 +64,7 @@
   '        def dummy2():\n'
   '            """Function docstring"""\n'
   '        ####################################\n'
-  '        # This comment \n'
+  '        # This comment\n'
   '        #%%\n'
   '        # and this comment inside python indentation\n'
   '        # breaks the block structure and is not\n'
@@ -76,13 +72,13 @@
   '            dummy2\n'
   '\n',
   53),
- ('code',
+('code',
   '\n'
   '"""Free strings are not supported. They will be rendered as a code '
   'block"""\n'
   '\n',
   67),
- ('text',
+('text',
   'New lines can be included in your text block and the parser\n'
   'is capable of retaining this important whitespace to work with Sphinx.\n'
   'Everything after a block splitter and starting with ``#`` then one space,\n'
@@ -92,9 +88,11 @@
   'rST header within text block\n'
   '^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n',
   71),
- ('code', "\nprint('one')\n\n", 79),
- ('code', '\n# another way to separate code blocks shown above\nB = 1\n\n', 84),
- ('text',
+('code', "\nprint('one')\n\n", 79),
+('code',
+  '\n# another way to separate code blocks shown above\nB = 1\n\n',
+  84),
+('text',
   'Last text block.\n'
   '\n'
   "That's all folks !\n"
@@ -102,4 +100,4 @@
   '.. literalinclude:: plot_parse.py\n'
   '\n'
   '\n',
-  89)]
+  89)]
\ No newline at end of file