Skip to main content

Rendering Jupyter notebooks to HTML

How to execute notebooks reproducibly and save the output to the results folder

Updated over 5 years ago

While Jupyter notebooks are commonly used interactively, with cells executed individually, to publish on Code Ocean, we ask that notebooks be executed as a whole. This allows notebooks to serve as a reproducible record of the analysis from start to finish.

To do so, add commands* to your master script to execute jupyter nbconvert  with the --execute  flag listed. This renders the final results into /results as an HTML file.

jupyter nbconvert \
  --ExecutePreprocessor.allow_errors=True \
  --ExecutePreprocessor.timeout=-1 \
  --FilesWriter.build_directory=../results \
  --execute notebook.ipynb

Notes

  • The --ExecutePreprocessor.allow_errors=True flag isn't strictly necessary, but will reveal errors within the notebook, which makes debugging much easier.

  • The --ExecutePreprocessor.timeout=-1 flag will disable execution timeouts, allowing each cell to take as much time as it needs to execute.

  • If you are using Python 3 you may need to specify the following flag:
    --ExecutePreprocessor.kernel_name="python3"
     

  • Code Ocean currently strips out the inline results from notebooks in the /code pane. This showcases that all notebooks in the /results  have been successfully rendered in the Code Ocean environment.

  • See nbconvert's excellent documentation for more details

*These commands can also be used to render a Jupyter notebook directly from the command line.

Did this answer your question?