Open Tech Strategies's Document Infrastructure
This is Open Tech Strategies' infrastructure for building our published documents from their source files. Most of the documents are written in LaTeX, though we sometimes use other formats too.
The expected audience is people who want to work with the source text of our published reports. If you have the source repository for a given report, and you have this infrastructure, you should be able to re-create the published report (usually a PDF). Please let us know if you have difficulty doing so. We always welcome suggestions for improving this infrastructure.
Installation
-
Install the system software prerequisites.
Make sure
pdflatex
andlatexmk
are installed on your system already. -
Set up the
OTS_DOCTOOLS_DIR
environment variable.Set the environment variable OTS_DOCTOOLS_DIR to point to the directory where you have this source tree checked out. For example, put something like this in your
~/.bashrc
:OTS_DOCTOOLS_DIR=${HOME}/src/ots-doctools export OTS_DOCTOOLS_DIR
-
Set up the
TEXMFHOME
environment variable.Set the TEXMFHOME variable so that that kpathsea can find
latex/*
in this directory. For example, putTEXMFHOME=${HOME}/texmf export TEXMFHOME
in your
~/.bashrc
, and make sure that~/texmf/tex/latex/ots
is a symlink to${OTS_DOCTOOLS_DIR}/latex
. (Because kpathsea sometimes behaves oddly, we also recommendmkdir ~/texmf/tex/latex/dummy
so that kpathsea will follow the symlink properly.)
Usage
The top-level Makefile
in your document's source tree -- remember,
that's a different tree from this one -- should be a copy of the file
ext-Makefile
here. If you got the document tree from us, that will
already be the case. Just run
$ make foo.pdf
to build foo.pdf
from foo.ltx
. For draft PDFs, use make foo.draft.pdf
.
Pipeline and Plugins
We have enabled the use of jinja templates. The Makefile runs pipeline.py, which applies a series of plugins to the document and its metadata. Each plugin can implement run(document, metadata) that returns doucment, metadata. Optionally, a plugin might implement run_p(document, metadata) that returns true iff the plugin should run.
Plugins might also implement after and after_p, which get run after the doc is built. These plugins might operate on the pdf or do post-build cleanup tasks.
A well-behaved plugin should have some way to disable itself in the
doc. One easy method is to honor flags: if the user sets
"PlUGIN_NAME: False" in the doc's YAML preamble, then run_p can return
meta.get('PLUGIN_NAME', True) != False
We load and run plugins in asciibetical order and skip ones whose names start with something other than a digit or a number. This allows users to disable a plugin by prefixing its name with an underscore.
See the plugins in ./pipeline/plugins for documentation on specific plugins.
Windows
Linux and OS X should generally do the right thing with these materials. We have not documented how to set this up on Windows because we haven't tried that setup. If you're on Windows, please let us know how it goes and how we can improve these materials.
Dependencies
You'll need Python3 and the items in requirements.txt
. You can
install the latter with pip3 install -r requirements.txt
or use your
usual python dependency management system.