Global build env and configuration

[phockett]

To do, probably first.

• HTML vs. latex/PDF build settings (mainly plotters probably). May also want to use exclude on filenames to allow for different versions of content (although ideally will not need to do this).
• Imports for each notebook? General script as per PEMtk config? (https://github.com/phockett/PEMtk/blob/master/demos/fitting/setup_fit_demo.py)
• Global substitutions? https://jupyterbook.org/content/content-blocks.html#define-substitutions-for-your-whole-book
• Cleanest env config probably to use Docker? Easy to ensure env consistency and tear-down/rebuild/test cycles. See https://github.com/phockett/open-photoionization-docker-stacks

General setup & config notes: https://github.com/phockett/Quantum-Metrology-with-Photoelectrons-Vol3/tree/main/notes/jupyter_book

[phockett]

Global substitutions? jupyterbook.org/content/content-blocks.html#define-substitutions-for-your-whole-book

In testing Nov. 2022 this is working nicely, EXCEPT NEED TO USE "string" for subs in _config.yml in general, otherwise sometimes get syntax issues.

[phockett]

Added general notebook setup script, 6bc38bb715feab2d93bfe6b246b607d2ad8b0bec

[phockett]

For more on build chain methods and customisations (currently can't pass env vars directly):

• https://jupyterbook.org/en/stable/advanced/sphinx.html (Sphinx config)
• https://github.com/executablebooks/jupyter-book/issues/1673 (general discussion re: dynamic vars)
• https://github.com/executablebooks/jupyter-book/issues/1709 (env vars)
• https://github.com/UCB-stat-159-s22/site/blob/2e72b4c17795283362a4b02cde43a751eaa0eeaa/Makefile#L7 (custom sphinx build example)
• nbsphinx config and env, see https://nbsphinx.readthedocs.io/en/latest/configuring-kernels.html#Kernel-Arguments cf. ipypublish configs as used in the past, https://ipypublish.readthedocs.io/en/latest/nb_conversion.html)
• sphinx env (via conf.py), e.g. https://stackoverflow.com/questions/61216495/change-variable-in-sphinx-conf-py-as-part-of-build-command

Currently just thinking about a method to pass ENV vars through build chain for HTML vs. PDF figure config (https://github.com/phockett/Quantum-Metrology-with-Photoelectrons-Vol3/issues/2), but other issues might crop up later. Have done this type of thing in the past for ePSdata work with nbconvert & Sphinx native build chain.

TODO: test some methods, check ePSdata methods.

[phockett]

UPDATE: actually passing env vars to build chain is OK,

e.g.

export BUILDENV=pdf
jupyter-book build --builder pdflatex
unset BUILDENV

Works as expected, and buildEnv = os.getenv('BUILDENV') works in notebook or scripts. Now using this to fix Plotly figure glue() issues, see https://github.com/phockett/Quantum-Metrology-with-Photoelectrons-Vol3/issues/2.