Writing Tutorials

This is a short guide for writing ProDy tutorials that are published as part of online documentation pages, and also as individual downloadable PDF files.

Tutorial Setup

First go to doc folder in ProDy package and generate necessary files for your tutorial using start-tutorial.sh script:

$ cd doc
$ ./start-tutorial.sh
Enter tutorial title: ENM Analysis using ProDy
Enter a short title: ENM Analysis
Enter author name: First Last

Tutorial folders and files are prepared, see tutorials/enm_analysis

This will generate following folder and files:

$ cd tutorials/enm_analysis/
$ ls -lgo
-rw-r--r-- 1  328 Apr 30 16:48 conf.py
-rw-r--r-- 1  395 Apr 30 16:48 index.rst
-rw-r--r-- 1  882 Apr 30 16:48 intro.rst
-rw-r--r-- 1 1466 Apr 30 16:48 Makefile
lrwxrwxrwx 1   13 Apr 30 16:48 _static -> ../../_static

Note that short title will be used as filename and part of the URL of the online documentation pages.

If tutorial logo/image that you want to use is different from ProDy logo, update the following line in conf.py:

tutorial_logo = u'enm.png'     # default is ProDy logo
tutorial_prody_version = u''        # default is latest ProDy version

Also, note ProDy version if the tutorial is developed for a specific release.

Style and Organization

ProDy documentation and tutorials are written using reStructuredText, an easy-to-read/write file format. See reStructuredText Primer for a quick introduction.

reStructuredText is stored in plain-text files with .rst extension, and converted to HTML and PDF pages using Sphinx.

index.rst and intro.rst files are automatically generated. index.rst file should include title and table of contents of the tutorial. Table of contents is just a list of .rst files that are part of the tutorial. They be listed in the order that they should appear in the final PDF file:

.. _enm-analysis:

.. use "enm-analysis" to refer to this file, i.e. :ref:`enm-analysis`

*******************************************************************************
ENM Analysis using ProDy
*******************************************************************************


.. add .rst files to `toctree` in the order that you want them

.. toctree::
   :glob:
   :maxdepth: 2

   intro

Add more .rst files as needed. See other tutorials in doc/tutorials folder as examples.

Input/Output Files

All files needed to follow the tutorial should be stored in tutorial_name_files folder. There is usually no need to provide PDB files, as ProDy automatically downloads them when needed. Optionally, output files can also be provided.

Note

Small input and output files that contain textual information may be included in the git repository, but please avoid including large files in particular those that contain binary data.

Including Code

Python code in tutorials should be included using IPython Sphinx directive. In the beginning of each .rst file, you should make necessary imports as follows:

.. ipython:: python

   from prody import *
   from matplotlib.pylab import *
   ion()

This will convert to the following:

In [1]: from prody import *

In [2]: from matplotlib.pylab import *

In [3]: ion()

Then you can add the code for the tutorial:

.. ipython:: python

   pdb = parsePDB('1p38')

In [4]: pdb = parsePDB('1p38')

Including Figures

IPython directive should also be used for including figures:

.. ipython:: python

   @savefig tutorial_name_figure_name.png width=4in
   plot(range(10))

   @savefig tutorial_name_figure_two.png width=4in
   plot(range(100)); # used ; to suppress output

@savefig decorator was used to save the figure.

Note

Figure names needs to be unique within the tutorial and should be prefixed with the tutorial name.

Note that in the second plot() call, we used a semicolon to suppress the output of the function.

If you want to make modifications to the figure, save it after the last modification:

.. ipython:: python

   plot(range(10));
   grid();
   xlabel('X-axis')
   @savefig tutorial_name_figure_three.png width=4in
   ylabel('Y-axis')

Testing Code

If there is any particular code output that you want to test, you can use @doctest decorator as follows:

.. ipython::

   @doctest
   In [1]: 2 + 2
   Out[1]: 4

In [5]: 2 + 2
Out[5]: 4

Failing to produce the correct output will prevent building the documentation.

Publishing Tutorial

To see how your .rst files convert to HTML format, use the following command:

$ make html

You will find HTML files in _build/html folder.

Once your tutorial is complete and looks good in HTML (no code execution problems), following commands can be used to generate a PDF file and tutorial file achieves:

$ make pdf
$ make files

ProDy online documentation will contain these files as well as tutorial pages in HTML format.