Instructions for Developers
1.6. Instructions for Developers#
1.6.1. Getting started#
Download the source material from https://github.com/Speech-Interaction-Technology-Aalto-U/itsp.
Install required packages with e.g. conda/anaconda
conda install jupyter-book
Many chapters require further packages, which you should install if you plan to compile the whole book (not always required).
conda install numpy scipy matplotlib ipython ipywidgets jupyterlab pip install itikz
The typical use case is that markdown (.md) and notebooks (.ipynb) are written with JupyterLab, which can be started (in the folder of the project) by
jupyter lab &
The easiest way to start is to write static Markdown files. This disadvantage is that then you cannot use live code-examples in your document. Upgrading from markdown to notebooks is however easy.
Once you are reasonably happy with your new content, compile the html-book (in the folder of the project) by
jupyter-book build .
Verify that the html-book looks like intended - some elements might work slightly differently.
1.6.2. Tips and tricks#
22.214.171.124. Interactive elements#
Some demonstrations are best when readers get to modify parameters themselves and to observe the output. IPython and ipywidgets allows doing that. Unfortunately, some of the more advanced interactive elements currently require a running jupyter/python kernel (i.e. have to run the notebook on a server). For an example, check out Representations/Spectrogram and the STFT.
126.96.36.199. Flow graphs and other static visualizations#
Tip: In some scenarios, characters will get messed up when having multiple itikz-elements in a single document. If you’re having this issue, please see the solution at the discussion on Itikz-github.
188.8.131.52. References and citations#
184.108.40.206. Executing notebooks / MyBinder badge#
To allow for the user to run the code in notebooks, there needs to be a jupyter server. Such a server can be installed locally (see Using this document), but importantly, there are public servers which can be used as well. The simplest approach is to use mybinder.org. To make it simple to use, please place a badge on top of the notebook, which directly runs the notebook on the server with the following steps:
Find the github url, folder and filename.
Enter the above in the form at mybinder.org.
This autogenerates a command to generate the badge; copy that code to the top of your jupyter notebook.
Be sure to test it by clicking the badge. For an example of use, see the page Noise attenuation.