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## STOPor# STOPREFis 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.