Skip to main content

Inject Python calculations into Word and LaTeX documents with ease!

Project description

doCal

CircleCI

doCal is a tool that can be used to send calculations that are written in python to Word or LaTeX documents. It evaluates equations in a separate python script from the document and replaces hashtags in the document that indicate where the calculations should be with the results of the evaluation. It comes with a powerful python expression to LaTeX converter built-in, so it converts the calculations and their results to their appropriate LaTeX forms before sending them, which makes it ideal to make academic and scientific reports.

Installation

Requirements

Quick note: in this document, shell means cmd (command prompt) or powershell for Windows users and sh or bash for Linux and MacOS users.

A basic understanding of Python in general is necessary to have a smooth experience here. If you want to work with a little more advanvced stuff, like arrays and matrices, more knowledge about python is necessary.

It must be obvious by now but you should have Python installed on your system. You can check that by opening your shell (see above) and typing the command python and hitting Enter. If it writes the version number and other info about your python installation, you already have it installed. If the version number starts with 2, you should probably install python 3 (the latest). If you have python 3 or above, you're good to go. If either you don't have Python 3 or you don't have Python at all, you should go to Python's homepage and install it, making sure to check the box "add python to path" during installation.

If you want to work with word documents, you should have Pandoc installed on your system (and in your path). Because docal internally only works with tex files and when a word file is given, it internally converts it to tex, modifies it and converts it back to word, using pandoc.

Install

To install this package, (after making sure that you have a working internet connection) type the following command and hit Enter.

pip install docal

Or if you have the source

pip install .

Usage

Typical workflow

  • The user writes the static parts of the document as usual (Word or Latex) but leaving sort of unique hashtags (#tagname) for the calculation parts (double hash signs for Wrod).
  • The calculations are written on a separate text file with any text editor (Notepad included) and saved next to the document file. For the syntax of the calculation file, see below. But it's just a python script with comments.
  • The tool is invoked with the following command:
    [calculation-file] [input-file] [output-file]
    
    so for example,
    docal calcs.py document.tex document-out.tex
    
    will be valid.
  • Then voila! what is needed is done. The output file can be used normally.

Syntax

The syntax is simple. Just write the equations one line at a time. What you write in the syntax is a valid python file, (it is just a script with a lot of assignments and comments). The following should be a good starting point.

## foo.py
## necessary for scientific functions
from math import *

#foo

# The first side of the first triangle is
x_1 = 5 #m
# and the second,
y_1 = 6 #m
# Therefore the length of the hypotenuse will be,
z_1 = sqrt(x_1**2 + y_1**2) #m

#bar

# Now the second triangle has sides that have lengths of
x_2 = 3
y_2 = 4
# and therefore has a hypotenuse of
z_2 = sqrt(x_2**2 + y_2**2) #m,13

# Then, we can say that the hypotenuse of the first triangle which is #z_1 long
# is longer than that of the second which is #z_2 long.

Now, looking at the above example line by line,

  • The first part (starting with double hash signs) serves as a real comment that does not do anything in python or in docal.
  • The second is a python import statement, to make things such as sqrt, sin, pi available.
  • The line that only contains a hashtag is treated as a message that what follows, until the next tag or the end should be sent to the document and at this particular place. That's why tags are necessary in the document. It looks for those tags in the document and replaces them with the modified versions of the calculations and paragraphs below it.
  • The lines starting with single hash characters are taken as parts of running text (paragraphs).
  • The lines with equal signs are treated as calculations. when they end with comments, the part after the hash character is treated as options for that calculation. (in the first three cases, we want to display the unit m displayed besides the variables that we assign to. And in the last equation, the additional 13 is taken as thouth the user wants only the first and the last steps displayed.)
  • The last two comments (treated as paragraphs), have tags in them, which are interpreted as variable references and thus are substituted by formatted values of those variables.

The output of the above example, inserted into a plain word file, containing only two tags, ##foo and ##bar will look like the following figure.

Word document output

Known Issues

  • You cannot use python statements that need indenting. This is because docal reads the script line by line and uses exec to make the necessary assignments, and since you can't continue an already indented code with exec, that will result in an error. If you have an idea to overcome this problem, feel free to contact me.

TODO

Long term

  • Add unit awareness. Currently the units don't take part in the number manipulations. They just appear besides the values when a variable is referenced. This means the numbers will be the same with or without the units.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

doCal-0.3.1.tar.gz (14.5 kB view details)

Uploaded Source

Built Distributions

doCal-0.3.1-py3.7.egg (31.9 kB view details)

Uploaded Egg

doCal-0.3.1-py2.py3-none-any.whl (16.5 kB view details)

Uploaded Python 2Python 3

File details

Details for the file doCal-0.3.1.tar.gz.

File metadata

  • Download URL: doCal-0.3.1.tar.gz
  • Upload date:
  • Size: 14.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.20.1 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.7.1

File hashes

Hashes for doCal-0.3.1.tar.gz
Algorithm Hash digest
SHA256 32e438e67d037a3f07535273a8c27eab1569036c8e91dbab0d6efa2edb6420df
MD5 9759f2c2fbfb85c0a1d59eca717cf068
BLAKE2b-256 eda8944f1b8043d2bea290384c7910d8498cebe474526b31382156ce6257e6ce

See more details on using hashes here.

File details

Details for the file doCal-0.3.1-py3.7.egg.

File metadata

  • Download URL: doCal-0.3.1-py3.7.egg
  • Upload date:
  • Size: 31.9 kB
  • Tags: Egg
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.20.1 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.7.1

File hashes

Hashes for doCal-0.3.1-py3.7.egg
Algorithm Hash digest
SHA256 d7636617d35a7daefb6076c5ea4ef87dc60785c1185beb4e07dcf08da3b31ac6
MD5 b85926fef7ce6843627ddb9c6d9980c3
BLAKE2b-256 58e407fe165e0ca29bd9140d23defad9a4fb5209dcde4d14f7252531078da18d

See more details on using hashes here.

File details

Details for the file doCal-0.3.1-py2.py3-none-any.whl.

File metadata

  • Download URL: doCal-0.3.1-py2.py3-none-any.whl
  • Upload date:
  • Size: 16.5 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.20.1 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.7.1

File hashes

Hashes for doCal-0.3.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 fd67172e36746dc9709d93c319a1fca93a612629f5ec3f62646b544dbe7ba251
MD5 fa4c72aa48fe001662526f164da9de4f
BLAKE2b-256 7790d338da185b47f1331e1c4431304a65bac4ffd4a8ded5b82034ac2eeda3fd

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page