LaTeX Report with automated build process

Environment

Setup LaTeX

First of all a fully working LaTeX Environment is necessary. There are tons of tutorials to handle the installation.

http://www.tug.org/mactex/ (I've used this)
http://www.tug.org/texlive/

The local build automation process requires more tools to work:

https://mg.readthedocs.io/latexmk.html‌‌ used to build the pdf version
make (preinstalled on most unix systems)‌‌for windows: http://gnuwin32.sourceforge.net/packages/make.htm

I've used pandoc to generate other file formats based on my LaTeX report, like ms word or open document.

https://pandoc.org/installing.html

Setup VSCode

The full installation of LaTeX ships two different applications to work with LaTeX files (TeXworks or TeXShop). These are really powerfull and extensive editors. But I'm more famliar with development environments like IntelliJ or VS Code. For this reason I prefered to use VS Code. The following tutorial describes the vs code setup using the plugin LaTeX Workshop:

https://medium.com/@rcpassos/writing-latex-documents-in-visual-studio-code-with-latex-workshop-d9af6a6b2815

Visual Studio Code with LaTeX Workshop Plugin

Now the document bootstrap will be created. I need a report and a presentation based on the same content and references. Each chapter and section will be stored in separated files.

.
├── chapters
│   └── introduction
│       ├── abstract.tex
│       └── references.tex
├── figures
│   ├── images
│   ├── pdf
│   └── tables
├── keynote.tex
├── report.tex
└── shared-deps.tex

Dependencies

All shared dependencies are stored in shared-deps.tex file. The file will be imported by report.tex and keynote.tex. A working file can be downloaded on github.

% ----- Deps -- Figures and Graphics
\usepackage{graphicx} % https://ctan.org/pkg/graphicx
\usepackage{tikz} % https://ctan.org/pkg/pgf

All packages can be found on the Comprehensive TeX Archive Network. If your code does not fully relay on the LaTeX default installation you have to customize your deployment container.

Setup Document

Your report.tex file contains your main document definition. You can import each chapter file to get a better overview of the structure.

\documentclass[a4paper, 12pt]{report}
\input{shared-deps.tex} % Load shared dependencies

\begin{document}

    \begin{titlepage}
        % your titlepage
    \end{titlepage}
    
    \chapter{Intro}
    \input{chapters/intro/intro}
    
\end{document}

Add References

You can use different references systems. I've worked with biblatex and its own data backend called biber . Put all your references to a the bibliography.bib file. I've used BibDesk to manage my reference library.

@book{book:maintainable-software,
    Author = {Joost Visser, Sylvan Rigal},
    Isbn = {9781491953495},
    Keywords = {testing, benchmarking},
    Publisher = {O'Reilly Media},
    Title = {Building Maintainable Software - Java Edition},
    Year = {2016}}

Before you can use them, you have to import the required packages:

\usepackage[german]{babel} % Local language support
\usepackage[backend=biber,style=alphabetic]{biblatex}
\usepackage[hidelinks,bookmarks=true]{hyperref}
\addbibresource{bibliography.bib} % import glossary entries

Use references

Now you can use these entries in your report for example with the footnote command: \footnote{This is the content of footnote}. You can also use citiations in footnote with a custom style. Overwrite the \footcite command with your stylings. Place the code (from stackexchange) in your report.tex befor your document begins.

\DeclareCiteCommand{\footcite}[\mkbibfootnote] 
	{\usebibmacro{prenote}}                                 
	{\usebibmacro{citeindex}
		\printfield{labelalpha}
		\setunit{\labelnamepunct}
		\printfield[citetitle]{title}
	}
  {\addsemicolon\space}
  {\usebibmacro{postnote}}

Now you'll be able to use your layout with a key from your bibliography in your footnotes:

\footcite{book:maintainable-software}

Custom styled \footcite command

Print references

Print a list of your used references with the \printbibliography command in your report file where you want to place the page.

Output of command printbibliography

Add Glossaries

For glossaries and acronyms i've used the glossaries package. With this package you're able to store your entries in a separate file. In this file you define your glossary and acronym items as followed in the glossary.tex file:

\newacronym{go}{Go}{Golang}
\newglossaryentry{mutex}{
	name=Mutex,
	plural=Mutex,
	description={Englische Abkürzung für \textbf{m}utual \textbf{e}xclusion}
}

You can use this entries by importing the file in your report. Your glossary will be generated by the \makeglossaries command. To use these index in a automates pipeline with latexmk you have to add a .latexmk configuration. Follow this post to understand why.

\usepackage[acronym, toc]{glossaries} % https://ctan.org/pkg/glossaries

\makeglossaries
\loadglsentries{glossary}

Link your glossary and reference entries with the hyperref package.

If you run the report file in visual studio code you have to generate the index manually with the command: makeglossaries report .

Now you can print your glossarie tables with these commands:

\printglossary
\printglossary[type=\acronymtype, title=Begriffe und Abkürzungen, toctitle=Begriffe und Abkürzungen]

Output of command printglossary

Build Process

The report can now be built to a single pdf file. To simplify this process, use a Makefile with following content. Run make to build the document. Read the docs of the make tool to enhance the file.

# dependencies
# - gcc
# - latexmk

.PHONY: setup clean pub

REPORT_NAME = report
PRESENATION_NAME = keynote
OUT_DIR = dist/

all: clean setup report pub

setup:
    mkdir -p ${OUT_DIR}
    
report: report.tex
    latexmk -bibtex -diagnostics -jobname=${REPORT_NAME} --file-line-error --interaction=nonstopmode -pdf report.tex
   
keynote: presentation.tex
		latexmk -bibtex -diagnostics -jobname=${PRESENATION_NAME} --file-line-error --interaction=nonstopmode -pdf keynote.tex

pub:
    cp ${REPORT_NAME}.pdf ${OUT_DIR}
    cp ${PRESENATION_NAME}.pdf ${OUT_DIR}
    
clean: 
    latexmk -CA
    rm -rf dist
    rm -f ${REPORT_NAME}.pdf
    rm -f ${PRESENATION_NAME}.pdf

I've used a continuous build pipeline to archive my built reports.

Github Workflows

You can use for example github workflows. It's well integrated and easy to use. Create the file .github/workflows/build.yml and add following pipeline definition. I've used the action from xu-cheng. When the built process is finished, all files from dist folder will be available as zip archive to download.

name: build
on: [push, pull_request]

jobs:
    build_report:
        runs-on: ubuntu-latest
        name: Build Report
        steps:
          - name: Set up Git repository
            uses: actions/checkout@v2
          - name: Setup LaTeX
            uses: xu-cheng/latex-action@v2
            with:
              root_file: report.tex
          - uses: actions/upload-artifact@v2
            with:
              name: report
              path: report.pdf

CircleCI

You can also use the circleCI Service. The pipelines runs faster with this provider than github workflows. The free credits (2500) from circleci allows you to build the report about 70 (4m build time) to 140 (2m build time) times a week. Create a file named .circleci/config.yml and add following snippet. I've used the docker container from aergus.

version: 2
jobs:
  build:
    docker:
      - image: aergus/latex
    steps:
      - checkout
      - run:
          name: Build Case Study
          command: make all
      - store_artifacts:
          path: dist/
          destination: dist