Contents

To run this locally, install Ploomber and execute: ploomber examples -n cookbook/report-generation

Found an issue? Let us know.

Questions? Ask us on Slack.

Report generation

Generating HTML/PDF reports.

Ploomber makes it simple to generate HTML and PDF reports from notebooks and scripts. To see some examples, go to the reports/ directory. This cookbook covers several use cases and includes runnable examples.

HTML reports (easiest option)

HTML reports are the simplest option as they don’t require any extra dependencies. You only need to change the product extension to .html and Ploomber will do the conversion:

# Content of pipeline.yaml
    # scripts can generate reports
    - source: tasks/script.py
      name: html-report
      product:
        nb: reports/report.html
        # the task can generate more outputs, list them here

Runnable example:

# get example
pip install ploomber "nbconvert[webpdf]" --upgrade
ploomber examples -n cookbook/report-generation -o example
cd example

# install example dependencies
ploomber install

# generate HTML report
ploomber task html-report

Check out report at reports/report.html

PDF reports

To generate PDF reports there are two options, using chromium or TeX.

Using chromium (easiest pdf option)

To use use chromium, pass nbconvert_exporter_name: webpdf

# Content of pipeline.yaml
    # pdf report example
    - source: tasks/script.py
      name: webpdf-report
      # use the webpdf exporter (supportes embedded charts)
      # (it will download chromium if needed)
      nbconvert_exporter_name: webpdf
      product:
        nb: reports/report-webpdf.pdf

Runnable example:

# get example
pip install ploomber "nbconvert[webpdf]" --upgrade
ploomber examples -n cookbook/report-generation -o example
cd example

# install example dependencies
ploomber install

# generate PDF report
ploomber task webpdf-report

Check out report at reports/report-webpdf.pdf

Using TeX

TeX is the default, to use it, set the product extension to .pdf:

# Content of pipeline.yaml
    # pdf report example (requires latex)
    - source: tasks/script.py
      name: pdf-report
      # generate pdf report by changing the extension.
      product:
        nb: reports/report.pdf

Runnable example:

# get example
pip install ploomber "nbconvert[webpdf]" --upgrade
ploomber examples -n cookbook/report-generation -o example
cd example

# install example dependencies
ploomber install

# generate PDF report
ploomber task pdf-report

Check out report at reports/report.pdf

Installing TeX

For instructions on installing TeX, see this..

TeXLive is a large distribution, as an alternative, you may install BasicTeX. Here are instructions for macOS.

Upon BasicTeX installation, you’ll need to install a few extra packages:

# Note: if using macOS or Linux, you may need to execute with sudo
tlmgr install adjustbox \
  caption \
  collectbox \
  enumitem \
  environ \
  eurosym \
  jknapltx \
  parskip \
  pgf \
  rsfs \
  tcolorbox \
  titling \
  trimspaces \
  ucs \
  ulem \
  upquote

Source.

Hiding code

In many cases, you want to hide the code so the report only contains tables and charts, you can do so easily with the exclude_input option:

# Content of pipeline.yaml
    # notebooks as well
    - source: tasks/notebook.ipynb
      name: another-html-report
      product:
        nb: reports/another.html

      nbconvert_export_kwargs:
        # optionally hide the code from the report
        exclude_input: True

Runnable example:

# get example
pip install ploomber "nbconvert[webpdf]" --upgrade
ploomber examples -n cookbook/report-generation -o example
cd example

# install example dependencies
ploomber install

# generate HTML report and hide code
ploomber task another-html-report

Check out report at reports/another.html

Hiding cells

You may want to hide cells from the output notebook selectively. You can do so with the TagRemovePreprocessor, which takes a list of tags. Any cells with such tags are excluded:

# Content of pipeline.yaml
    # notebooks as well
    - source: tasks/notebook.ipynb
      name: another-html-report
      product:
        nb: reports/another.html

      nbconvert_export_kwargs:
        # optionally hide the code from the report
        exclude_input: True

        # optionally, exclude cells with certain tags
        config:
          HTMLExporter:
            preprocessors: [nbconvert.preprocessors.TagRemovePreprocessor]
          TagRemovePreprocessor:
            remove_cell_tags: [boxplot]

To learn how to add cell tags, see this.

Runnable example:

# get example
pip install ploomber "nbconvert[webpdf]" --upgrade
ploomber examples -n cookbook/report-generation -o example
cd example

# install example dependencies
ploomber install

# generate HTML report and hide boxplot
ploomber task another-html-report

Check out report at reports/another.html