- Difficulty level: easy
- Time need to lean: 10 minutes or less
- Key points:
- Magic
%convertexports notebook in other formats, mostly HTML - Multiple templates can be used through option
--template - Templates
sos-reportandsos-report-tocdepends on cell tags to hidden specified input and/or output of cells. - Templates
sos-report-v2andsos-report-toc-v2depends on cell hide/show status to determine the hide/show status of generated HTML report.
- Magic
Because it is not particularly easy to open an .ipynb file (a live Jupyter server is required) and because of risk of changing the content of an .ipynb file, it is often desired to save an .ipynb file in HTML format.
Jupyter makes use of a template system to control the content and style of exported HTML file. For example, you can use the default Jupyter template (File -> Save As -> HTML) to save all input and output cells, or you can use the hide code Jupyter extension to manually hide input or output of each cell and produce a customized .HTML file.
SoS provides its own template called sos-report, which can be used from command line using command
sos convert analysis.ipynb analysis.html --template sos-report
or from within Jupyter with magic %sossave with specified filename
%convert analysis.html -f
or using the same name as the notebook with option --to html
%convert --to html -f
Option -f overrides existing file if an output file already exists. You could also use other sos based templates such as sos-full, which displays all cells.
The sos convert command (and %convert magic) used the Jupyter conversion mechanism and calls nbconvert under the hood. Templates are written in Jinja2 format and are installed with sos-notebook. A list of templates can be seen from github:sos-notebook/src/sos_notebook/templates.
Template sos-full generates HTML reports that show all the cells. The sos-full-toc adds a dynamically generated table of content to the left of the report.
The sos-report template generates HTML reports with hidden contents. The report displays specified content when it is first opened, but users will be able to see the full report by selecting a drop down button at the top right corner of the report.
The display status of cells are controlled by the following tags
| tag | code cell input | code cell output | markdown cell |
|---|---|---|---|
| no tag | hidden | hidden | show |
scratch |
removed | removed | removed |
report_cell |
show | show | |
report_output |
show | ||
hide_output |
hidden |
The display-controlling tags can be toggled using keyboard shortcut Ctrl-Shift-O. For code cells, this shortcut will toggle report_output and mark cells with such a tag with a gray bar to the right of the output area, and the input will by default always be hidden. The report_cell and scratch tag has to be manually added through the tag toolbar (View -> Cell Toolbar -> Tags). Whereas report_output only works for output of code cells, the scratch tag applies to both markdown and code cells.
Since JupyterLab allows the open/close of both input and output of cells, there is no real need to use cell tags to control the display of contents.
Using templates sos-report-v2 and sos-report-toc-v2, you only need to hide the input and/or output of cells in the JupyterLab interface, and the hidden content will be hidden in the generated reports.