Skip to content

Latest commit

 

History

History
43 lines (38 loc) · 2.61 KB

README.md

File metadata and controls

43 lines (38 loc) · 2.61 KB
Raw

JupyTeX

pypi-badge

Provides Jupyter-backed execution of LaTeX code environments, and embeds the results. Similar in concept to PythonTex, but focuses on code execution, and avoids any language specific features.

Install with pip install jupytex.

How to Use

  1. Run jupytex install in LaTeX project directory (or provide an install directory with -d DIR) to create the necessary .latexmkrc and jupytex.sty files
  2. Add \usepackage{jupytex} to the document header
  3. Declare code environments with 
    \begin{code}{language}[opts]
    Some source code
\end{code}
    See the configuration section for valid options in opts.
  4. Run jupytex make (which is a pass-through to latexmk --shell-escape) to invoke latexmk.

Example Python Script

\begin{code}{python}[kernel=python3]
    print("$x + y = z$")
\end{code}

Removing from Project

Run jupytex uninstall in LaTeX project directory (or provide an install directory with -d DIR) to remove the installed .latexmkrc and jupytex.sty files

Cleaning Files

Run jupytex clean (which is a pass-through to latexmk -c or latexmk -C) to remove both LaTeX and JupyTex-related run files.

Flow Control

  1. jupytex.sty declares dependency upon \jobname.timestamp
  2. jupytex.sty macro writes code blocks to numbered .code files and attempts to include results
  3. Code 'blocks' are written to a \jobname.blocks csv file
  4. jupytex hash is invoked to calculate the md5 hash for all of the blocks, which is written to \jobname.hash. In future this should only be performed per-kernel-session.
  5. If \jobname.hash has been modified, jupytex execute is invoked for the corresponding job, the code blocks executed, and results written to .result files, and errors to .traceback files. Code blocks which do not write to stdout write an empty results file. \jobname.timestamp is updated with new timestamp.
  6. latexmk performs a new pass for the dependencies upon \jobname.timestamp

Configuration

  • Each code block must be given a language.
  • One can specify the Jupyter kernel name with a kernel key parameter, which will be used instead of the language if present. One can also access an existing kernel, by passing the name of a connection file.
  • A session key parameter may be passed to create a new kernel associated with the kernel-session pair. If the kernel parameter is set to a connection file, then this will create a new client to the same kernel.