Core Dox Render Module (tendril.dox.render)

This module provides the underlying rendering functions to produce PDF output. Other tendril.dox modules should use these functions to generate their output files.

Processors

format_currency(value) Formats a number into the correct number of decimals (2) and with thousands separators ,, for use when rendering currencies.
escape_latex(string[, aggressive]) Escapes latex control and reserved characters from the string.
jinja2_pdfinit() Creates a jinja2.Environment, stored in this module’s renderer_pdf variable.

Renderers

render_pdf(stage, template, outpath[, ...]) Render the latex output and convert it into pdf using pdflatex.
render_lineplot(outf, plotdata, title, note) Renders a lineplot to PDF.
make_graph(outpath, plotdata_y[, ...]) Renders a graph of the data provided as a .png file, saved to the path specified by outpath.
make_histogram(outpath, plotdata_y[, bins, ...]) Renders a histogram of the data provided as a .png file, saved to the path specified by outpath.
tendril.dox.render.format_currency(value)[source]

Formats a number into the correct number of decimals (2) and with thousands separators ,, for use when rendering currencies.

This function is added to the jinja2 PDF environment constructed by jinja2_pdfinit(), and is available as a filter in jinja2 templates.

Return type:str
tendril.dox.render.escape_latex(string, aggressive=True)[source]

Escapes latex control and reserved characters from the string. It also converts None type inputs into an empty string.

This is also where ‘special’ string sequences are defined to produce specialized latex output, such as the conversion of INR to the rupee symbol, via the latex \rupee~ command provided by tfrupee.

Parameters:string – Input string
Returns:Latex-safe string
tendril.dox.render.jinja2_pdfinit()[source]

Creates a jinja2.Environment, stored in this module’s renderer_pdf variable.

Application code would typically not call this function or interact directly wih the renderer, and instead use the various render functions provided in this module. If the renderer is required, the instance at tendril.dox.render.renderer_pdf can be used.

Environment Information

The environment created here is optimised to produce latex output.

Loader

jinja2.FileSystemLoader, with it’s root at tendril.utils.config.DOX_TEMPLATE_FOLDER

Template Markup Strings

  • Blocks: %{      %}
  • Variables: %{{    %}}
  • Comments: %{#    %#}

Filters

Returns:The jinja2 Environment.
tendril.dox.render.renderer_pdf = <jinja2.environment.Environment object>

The jinja2 environment which application code can use to produce latex output.

tendril.dox.render.render_pdf(stage, template, outpath, remove_sources=True, verbose=True, **kwargs)[source]

Render the latex output and convert it into pdf using pdflatex.

The stage is a dictionary passed on to the jinja2 environment, as is available within the template. This function adds some common variables to the stage.

This function makes three pdflatex passes to make sure all the references are resolved.

This function will remove the sources, i.e., the .tex files and intermediate files produced by pdflatex, after conversion. It will do so after running pdflatex, irrespective of the result. If the raw .tex file is needed (typically for debugging templates), the remove_sources parameter should be used.

Parameters:
  • stage (dict) – A dictionary which will be available to the template
  • template (str) – The template file to use, either relative to the loader’s template root or an absolute path.
  • outpath (str) – The path to the output file (including .pdf).
  • remove_sources (bool) – Whether to remove the latex files after conversion.
Returns:

outpath

Stage Keys Provided

logo The company logo, as specified in tendril.utils.config.COMPANY_LOGO_PATH
company The company name, as specified in tendril.utils.config.COMPANY_NAME
company_email The company email address, as specified in tendril.utils.config.COMPANY_EMAIL
company_address_line The company address, as specified in tendril.utils.config.COMPANY_ADDRESS_LINE
company_iec The company IEC, as specified in tendril.utils.config.COMPANY_IEC
render_ts The current timestamp
tendril.dox.render.render_lineplot(outf, plotdata, title, note)[source]

Renders a lineplot to PDF. This function is presently used to generate PCB pricing graphs by tendril.dox.gedaproject.gen_pcbpricing. It’s pretty unwieldy, and is likely going to be axed at some point in favor of make_graph(), once the necessary functionality is implemented there and the pricing graph code is modified to use that instead.

Warning

This function is likely to be deprecated.

See also

make_graph()

Parameters:
  • outf – The path to the output file.
  • plotdata – The data to plot.
  • title – The title of the plot.
  • note – An additional note to include with the plot (not implemented)
Returns:

outf
tendril.dox.render.make_graph(outpath, plotdata_y, plotdata_x=None, color='black', lw=2, marker=None, xscale='linear', yscale='linear', xlabel='', ylabel='', ymax=None, ymin=None)[source]

Renders a graph of the data provided as a .png file, saved to the path specified by outpath. This function uses matplotlib.pyplot.

Parameters:
  • outpath (str) – The path to the output file
  • plotdata_y (list) – The y-axis data to plot
  • plotdata_x (list or None) – The x-axis data to plot, or None if a plotdata_y is a sequence
  • color (str) – The color of the curve, default black. See matplotlib docs.
  • lw (int) – The linewidth of the curve, default 2. See matplotlib docs.
  • marker (str) – The marker to be used, default None. See matplotlib docs.
  • xscale (str) – The scale of the x axis, default linear. See matplotlib docs.
  • yscale (str) – The scale of the y axis, default linear. See matplotlib docs.
  • xlabel (str) – The x-axis label, default ''
  • ylabel (str) – The y-axis label, default ''
Returns:

The output path.
tendril.dox.render.get_optimum_bins(plotdata_y)[source]

Histogram Binwidth Optimization Method

Shimazaki and Shinomoto, Neural Comput 19 1503-1527, 2007
2006 Author Hideaki Shimazaki, Matlab
Department of Physics, Kyoto University
shimazaki at ton.scphys.kyoto-u.ac.jp

This implementation based on the version in python written by Érbet Almeida Costa

Parameters:plotdata_y – The data for which a histogram is to be made
Returns:The optimal number of bins

Warning

This function fails if the provided data lacks a proper distribution, such as if there are only 4 distinct values in the output. Figure out why and how to fix it. In the meanwhile, specify bins manually to not let this function be called.

tendril.dox.render.make_histogram(outpath, plotdata_y, bins=None, color='red', xlabel='', ylabel='', x_range=None)[source]

Renders a histogram of the data provided as a .png file, saved to the path specified by outpath. This function uses matplotlib.pyplot.

See also

get_optimum_bins()

Parameters:
  • outpath (str) – The path to the output file
  • plotdata_y (list) – The y-axis data to plot
  • bins (int or None) – Number of bins to use. If None, uses the optimum. See matplotlib docs.
  • color (str) – The color of the curve, default red. See matplotlib docs.
  • xlabel (str) – The x-axis label, default ''
  • ylabel (str) – The y-axis label, default ''
  • x_range (tuple) – The x-axis range, if not the default. See matplotlib docs for range.
Returns:

The output path.