

.. _sphx_glr_tutorials_plot_parse.py:


The Header Docstring
====================

When writting latex in a Python string keep in mind to escape the backslashes
or use a raw docstring

.. math:: \sin (x)

Closing this string quotes on same line

Direct first comment
with second line



.. code-block:: python


    import numpy as np








.. code-block:: python

    A = 1

    import matplotlib.pyplot as plt







There is no need to always alternate between code and comment blocks
Now there is free repetition of both


And a single line of hashes can split your blocks


Latex in the comments does not need to be escaped

.. math::
   \sin



.. code-block:: python


    def dummy():
        """This should not be part of a 'text' block'"""

        ######################################
        # Comment inside code to remain here
        pass

    # this should not be part of a 'text' block







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

Making a line cut in sphinx


.. warning::
    The next kind of comments are not supported and become to hard to escape
    so just don't code like this.

.. code-block:: python

    def dummy2():
        """Function docstring"""
    ####################################
    # This comment inside python indentation
    # breaks the block structure and is not
    # supported
        dummy2




.. code-block:: python


    """Free strings are not supported they remain part of the code"""







New lines can be included in you block comments and the parser
is capable of retaining this significant whitespace to work with sphinx

So the reStructuredText headers survive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



.. code-block:: python



    print('one')





.. rst-class:: sphx-glr-script-out

 Out::

    one


Code block separators
##############################################################################
 Surrounding a comment line with lines of # like a block spliter also
 works and creates a new header for that comment block
 too. Nevertheless to get rich text formatting we advise to use
 RestructuredText syntax in the comment blocks.



.. code-block:: python


    print('two')




.. rst-class:: sphx-glr-script-out

 Out::

    two



.. code-block:: python

    B = 1







End comments

That's all folks !

.. literalinclude:: plot_parse.py




**Total running time of the script:** ( 0 minutes  0.000 seconds)



.. only :: html

 .. container:: sphx-glr-footer


  .. container:: sphx-glr-download

     :download:`Download Python source code: plot_parse.py <plot_parse.py>`



  .. container:: sphx-glr-download

     :download:`Download Jupyter notebook: plot_parse.ipynb <plot_parse.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.readthedocs.io>`_
