engcom

Submodules

Package Contents

Classes

Publication

For publishing Python scripts (.py) and notebooks (.ipynb).

Functions

figure_markup(filename, caption, label)

show

Show the most recent figure (for publication)

Attributes

fignum

class engcom.Publication(title=None, author=None, source_filename=None)

For publishing Python scripts (.py) and notebooks (.ipynb).

This class allows you to publish Python scripts (.py) and notebooks (.ipynb) to standalone output files of types pdf and docx or to output files of types md (Markdown) and tex (LaTeX) that can be included in another document.

title

The title of the publication

author

The author of the publication

subtitle

The subtitle of the publication

Parameters:

  • title (str | None) – The title of the publication

  • author (str | None) – The author of the publication

  • source_filename (str | None | pathlib.Path) – The filename of the source file

basenamer(filename)

Return the basename of the filename (sans path and extension).

run()

Runs the temporary ipynb.

filter_absolute_path()

Returns the absolute path of the Lua filter filter.lua.

reference_doc_absolute_path()

Returns the absolute path of the Pandoc reference docx document pandoc_reference.docx.

write(to, pdflatex=True, tmp=False, clean=True)

Writes the publication to a file of type to.

With two types of output file (argument to), "docx" and "pdf", are standalone in the sense that they are complete documents ready for distribution. With the other two types of output file, "md" and "tex", a document intended to be included in another document is created.

To use to="pdf" with pdflatex=True (default), you must have LaTeX installed. Any will do, but our favorite is TeX Live, which works on all major operating systems. To use to="pdf" with pdflatex=False, you must have Microsoft Word installed. The use here of the docx2pdf package is buggy, so mileage may vary.

Parameters:

  • to (str) – Format to write to ("pdf", "docx", "md", "tex")

  • pdflatex (bool) – Use LaTeX to create a pdf (default: True)

  • tmp (bool) – Create a temporary output files (may be deleted by clean; default: False)

  • clean (bool) – Delete temporary output files (default: True)

Returns:

None

Example

It can be used from within the file to be published, call it pub.py as follows:

# %% This is a code cell
x = 3

# %% [markdown]
# Here is a Markdown cell with some math: $x = 4$.

# %% Another code cell
x**2

# %% [markdown]
## Here Is a Header
# And some regular text.

# %% Another code cell
x**3 + 1

# %% tags=["active-py"]
# This cell will not appear in the output due to its tag
import engcom
pub = engcom.Publication(title="A Title", author="Your Name")
pub.write(to="pdf")

This publishes a pdf file pub.pdf that appears as follows:

../../_images/pub.png

A published pdf file.

Alternatively, the last cell could be left off and another file could be used to publish it:

import engcom
pub = engcom.Publication(
    source_filename="pub.py", title="A Title", author="Your Name"
)
pub.write(to="pdf")

Finally, a third alternative is to use the publish CLI from a terminal window:

publish pub.py pdf --title "A Title" --author "Your Name"

In this example, we have used the "pdf" output for publishing. This requires installing LaTeX; see Installing LaTeX for Publishing PDF Files. Alternatively, "docx" could be used to create a Microsoft Word document. Finally, Markdown "md" and LaTeX "tex" can be used if you would like to include the published file in another document.

cleanup()

Delete temporary files

is_notebook()

Returns True if executed from a Jupyter notebook.

Return type:

bool

engcom.fignum = 0
engcom.figure_markup(filename, caption, label)
engcom.show(fig, filename=None, caption='', label=None, figsize=(4, 4 / 1.618))