Suport for parametrized books/pages

[grst]

As discussed in #113, I suggest adding support for parametrized books or single-pages.

Rationale

• enables to run notebooks as re-useable scripts
• useful for automated reporting from reproducible pipelines
• bookdown supports it so we want that, too ;)

Design choices and open questions

• papermill support parametrization of notebooks by overriding variables in a cell tagged with parameters at the beginning of the notebook. That sounds like a decent approach.
• We could either depend on papermill or integrate the relevant code sections into jupyterbook. As far as I can tell papermill does not have any heavy dependencies except for those that are already needed by jupyterbook, so I'd say it would be ok to depend on it.
• Papermill handles the execution of notebooks. If we decide to use it, we could consider using it for --execute.
• Command-line interface: Something along the lines of

jupyter-book page myreport.ipynb --execute --params="key1=value1 key2=value2"

Papermill also supports reading parameters from a yaml file, which is nice:

jupyter-book page myreport.ipynb --execute --params_file parameters.yml

• How to handle the parametrization of books that consist of multiple notebooks? Pass parameters for each notebook individually or a global set of parameters that is passed to all notebooks? To me the latter option seems preferable. Each notebook will only receive those parameters declared in the parameters cell.

Let me know what you think!

[choldgraf]

I’d be fine depending on papermill...it’s a community-supported project and I agree gives us a better ceiling for expanding functionality if we like.

[jeff-tilton]

I just want to add that it would be nice to have dynamic parameters. I am making a report that the parameters could change year to year depending on the output of a calculation. So the calculation will be run in one notebook, the output will serve as the parameters for the parameterized one. I am struggling on how I will implement this currently. I am just starting out with jupyter-book and love it so far so thank you! I look forward to parameterized notebook support.

[Nintorac]

Just throwing in an idea/use case.

I have a notebook that does a query to fetch the same parameter from two different datasets and then compares the distributions. In my database I have many parameters and am currently using papermill to render a notebook per parameter.

It would be cool to be able to declare something like this in the toc

format: jb-book
root: index
parts:
  - caption: Name of Numbered Part 1
    numbered: True  # Only applies to chapters in Part 1.
    chapters:
    - template_file: path/to/part1/chapter1
       parameters:
       - param_a: 1
         param_b: 2
       - param_a: 4
         param_a: 5

and have a page rendered for each item in the parameters array