:py:mod:`engcom`
================

.. py:module:: engcom


Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   data/index.rst
   models/index.rst
   publication/index.rst
   publish/index.rst
   show/index.rst
   tufte/index.rst


Package Contents
----------------

Classes
~~~~~~~

.. autoapisummary::

   engcom.Publication



Functions
~~~~~~~~~

.. autoapisummary::

   engcom.figure_markup
   engcom.show



Attributes
~~~~~~~~~~

.. autoapisummary::

   engcom.fignum


.. py:class:: 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.

   .. attribute:: title

      The title of the publication

   .. attribute:: author

      The author of the publication

   .. attribute:: subtitle

      The subtitle of the publication

   :param title: The title of the publication
   :param author: The author of the publication
   :param source_filename: The filename of the source file

   .. py:method:: basenamer(filename)

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


   .. py:method:: run()

      Runs the temporary ipynb.


   .. py:method:: filter_absolute_path()

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


   .. py:method:: reference_doc_absolute_path()

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


   .. py:method:: 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 <https://www.tug.org/texlive/>`_, 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.

      :param to: Format to write to (``"pdf"``, ``"docx"``, ``"md"``, ``"tex"``)
      :param pdflatex: Use LaTeX to create a pdf (default: ``True``)
      :param tmp: Create a temporary output files
                  (may be deleted by ``clean``; default: ``False``)
      :param clean: Delete temporary output files (default: ``True``)

      :returns: ``None``

      .. rubric:: Example

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

      .. code-block:: python

          # %% 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:

      .. figure:: /figures/pub.png

          A published pdf file.

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

      .. code-block:: python

          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:

      .. code-block:: bash

          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 :ref:`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.


   .. py:method:: cleanup()

      Delete temporary files


   .. py:method:: is_notebook()

      Returns True if executed from a Jupyter notebook.



.. py:data:: fignum
   :value: 0

   

.. py:function:: figure_markup(filename, caption, label)


.. py:function:: show(fig, filename=None, caption='', label=None, figsize=(4, 4 / 1.618))