.. _how to write tutorials: Documentation for writing tutorials =================================== It is recommended for contributors to add or update tutorials to describe new changes or better explain existing features of ``qnngds``. In order to write a tutorial, a small set of scripts has been provided that provides a limited `literate programming `_ functionality. In this way, your tutorial code can be written as a runnable file which is useful for performing unit tests to verify that the tutorial is up to date with any changes made to ``qnngds``. Note that the current implementation is quite hacky and has limited functionality compared to more fully-fledged suites like `Literate.jl `_, however I could not find any actively maintained tools for python that offer similar functionality. See the existing tutorials in ``docs/src/tutorials/`` for examples. Any line that starts with a comment will be added to the reStructured text output, and the rest is treated like code. The parser works by reading all python files in ``docs/src/tutorials``, line-by-line. It groups similar lines into "blocks", starting a new block when changing between comments and code, as well as when directives/special commands are passed to the parser. There are several special comments, each starting with a ``##``: * ``## IMAGE``: display an image generated by quickplot * ``## IMAGE_ZOOM``: display a zoomed image generated by quickplot * ``## STOP``: stops parsing the file and emits the source code (without comments) under a subsection labeled "Reference" at the end of the document. * ``## STOPNOREF``: stops parsing the file, does not emit the source code. One of ``## STOP`` or ``# STOPREF`` is required. * ``## SKIPSTART``, ``## SKIPSTOP``: defines stop/start regions for the parser to ignore, e.g. for code used to generate and save plots. The parser is located in ``docs/src/generate_tutorials.py``, and plot generation is done with ``save_qp``, defined in ``docs/src/tutorials/_save_qp.py``.