Phpytex transpiles hybrid code (ordinary LaTeX files augmented by blocks of python code) to a python script, which in turn generates a single LaTeX file (which in turn may be optionally compiled to pdf), i.e.

augmented code ⟶ python script ⟶ single .tex [⟶ pdf]

Phpytex allows you interweave inline python code, python code blocks, and text blocks across multiple files, incorporating global variables and imports. It allows you to manage complex document structures and generate single file outputs. This can be demonstrated in the cases in the examples subfolder. Each case contains a set of initial files and a counterpart folder with the outputs.

• Bash (windows users may install git/bash for windows)
• Python 3 (currently developed under python 3.9.5)

Follow the instructions in install/README.md. This will enable you to call phpytex within any project containing a .phpytex.yml config file.

• phpytex or phpytex help displays a message with the commands.
• phpytex version displays in plain text the version number.
• phpytex run [file=<name of config file>] runs the programme within a project using the named config file.
  If the file flag is left empty, the programme searches for the first yaml-file matching the pattern *.(phpytex|phpycreate).(yml|yaml) and uses this as the config file.

To use phpytex, a .phpytex.yml file is required in the (root of) the project folder. This should contain 4 parts with the following structure:

########################################
# COMPILE OPTIONS
########################################
compile:
  root:   root.tex
  output: main.tex
  ...
########################################
# STAMP OPTIONS (optional)
########################################
stamp:
  file:      stamp.tex
  overwrite: true
  options:
    ...
########################################
# DOCUMENT PARAMETERS (optional)
########################################
parameters:
  file: src.parameters
  overwrite: true
  options:
  ...
########################################
# DOCUMENT TREE (optional)
########################################
files:
  ...
folders:
  ...

See LONGREADME.md for more details and see the examples subfolder for concrete examples.

There are many (insert language here)-to-LaTeX transpilers available. And many of these do all sorts of fancy things like incorporate lots of extra special syntax to embed plots, etc. By contrast our transpiler is intentionally designed to be 'boring' (=sufficently general)! It has no built-in 'We can produce these cool graphics with this one command!'¹ selling point.

And neither—in our opinion—does it need to.

By our philosophy, the only things a transpiler should do are:

• assume the user can already use {python,LaTeX};
• not burden the user with a bunch of extra syntax beyond an absolute minimum (e.g. markdown languages achieve this wonderfully);
• reliably incorporate the full generality of features of an ordinary (python) coding project; and
• leave the bells-and-whistles (generation of graphics, usage of complex mathematical objects, data-frames, etc.) completely over to the user's imagination and mastery of both languages.

That is, transpilation allows the user to marry the two languages with little effort but in as generic a manner as possible, leaving the specific applications over to the user.

Furthermore Phpytex was originally conceived for the personal reason to

• allow the user to easily manage complex folder structures and generate a single-file-output.

And this shall remain a cornerstone feature of Phpytex.