How I wrote a diploma in LaTeX with GitHub, Docker and TravisCI

Original article in Russian on habr.com.

When I studied at university I heard about LaTeX course on Coursera “Introduction to LaTeX” and after that I started to use it for my laboratory and course works.

In this article I’ll tell you about how I wrote my diploma in LaTeX with unusual stack of instruments and technologies.

So with the help of simple devices, a loaf of white (or black) bread can be turned into a trolleybus. But why?

Introduction

My way of editing and creating documents started in school with Microsoft Word, probably as many of us. Then I changed OS from Windows to Linux and started to use OpenOffice and then LibreOffice. And, honestly, I didn’t noticed a difference between WYSIWYG editors.

I had a hurt in some situations when I wrote some essay in library’s computer class using OpenOffice and then wanted to print it on admin’s computer on Windows with Microsoft Word. Of course sometimes text formatting written in Open/LibreOffice behaved unpredictably on Word and vice versa. No one explained to me about exporting document to PDF before printing and relieve my pain, I learned about it when I studied at university when I printed documents almost every day.

Let’s back to LaTeX. Before using it, all that I heard about LaTeX is about scientific articles and it’s a good tool for documents with math formulas. For those who thinks the same, I recommend to listen a course on Coursera, it could change your opinion about LaTeX as an alternative for documents.

Hello, World using LaTeX:

\documentclass{article}
\begin{document}
Hello, World!
\end{document}

BTW, you can use LaTeX even for creating presentations. Here is a gallery of different presentations created with LaTeX.

Bachelor’s diploma with LaTeX

By the end of the third year in university I was already actively using LaTeX for processing almost all documents. And it was decided to write a bachelor’s diploma with LaTeX.

First time, I used LaTeXila as an IDE for LaTeX, where project was built with one button, it was possible to enable spell checking, but I sometimes it crashed and slowed down, so I started to use Sublime Text along with the Makefile.

Makefile:

all: build run
build:
latexmk -xelatex -synctex=1 main.tex
run:
xreader main.pdf &
clean:
rm *.aux *.fdb_latexmk *.fls *.log *.out *.synctex.gz *.toc

All source files stored in git, for convenience of collaboration with the scientific leader used GitHub. The project structure was very simple, in the main.tex file the preamble and other chapters were included, which were stored in a separate directory.

main.tex:

\documentclass[a4paper,14pt]{extarticle} % 14th font size
\input{inc/preamble} % Include preamble
\begin{document}
\tableofcontents % Table of contents
\clearpage
\input{inc/0-intro} % Introduction part
\input{inc/1-pz} % Problem statement part
...
\input{inc/0-bibliography} % Bibliography
\input{inc/a-app} % App A
\input{inc/b-app} % App B
\includepdf{act} % Include external PDF
\end{document}

A description of all styles and formatting is in the preamble.tex file, which is included at the beginning of the document.

It was very convenient not to care about formatting the ToC, bibliography and other parts of the diploma.

Table of contents

I will describe my advantages working with LaTeX, compared with WYSIWYG editors:

  • versioning (instead of diploma.odt, diploma_01.01.2015.odt, diploma_edited_for_print.odt — versioning in git and the ability to roll back to any commit)
  • if you accidentally pressed any key, the layout does not “fly off” (sometimes it happened with me)
  • flexible settings (which aren’t always available in WYSIWYG editors or they are not obvious)
  • same environment for everything (the source files of the presentation are in the same repository as the diploma’s source files)
  • possibility of collaboration (scientific leader can look in the repository for changes)
  • easy to use LaTeX templates for many different documents
  • easy to include some external sources as source code for or additional PDF

Here is an example of included file with source code:

\lstinputlisting[numbers=left]{inc/ddos-deflate/ddos.sh}
Included source code into document

There is only one disadvantage to using LaTeX for me — you need to take the time to polish everything to the desired result. Even I thought about redraw all charts and diagrams natively using TikZ, but it took a lot of time, so I used Google Drawings and draw.io for it.

Having successfully presentation of my bachelor’s diploma and gained some experience of working with git, GitHub, Makefile, TeX StackExchange, I forgot about the diploma for a couple of years in order to use my template to write my master’s diploma.

Master’s diploma

At the time when I was getting master’s degree, I already began to get involved in the tools of the engineer, such as Docker, began to practice with Continuous Integration tools, to learn the practices of DevOps. I was also interested with prettifying my pet open-source projects with README-files.

In general, when I started to write a master’s diploma, the requirements for formatting did not change much, so I took the template for my bachelor’s diploma and completed the little things. For example list of illustrations, a list of abbreviations and so on. When I presented a bachelor’s diploma, we used A1-sized posters, but in the presentations of master’s diplomas we were allowed to use presentations with slides, so I also edited slides using LaTeX and beamer.

Presentation created with LaTeX and beamer

Inspired by the concept of CI, I thought, why not collect a new PDF at each commit into the repository? Connecting GitHub to TravisCI took just a few minutes. Although TravisCI doesn’t know how to work directly with LaTeX, it works great with Docker. Cool, I thought, I’ll kill several birds with one stone:

  • practice writing Dockerfiles
  • migrate all the LaTeX packages to the Docker (and there are a lot of them and they are pretty heavy)
  • practice using TravisCI
  • help someone who wants to use my template on a different OS

Writing a configuration file for TravisCI, Dockerfile and editing the Makefile did not take a lot of time and it turned out to be convenient.

Makefile (part for docker):

...
docker:
docker build -t docker-latex .
docker run -ti -v ${PWD}:/master-thesis:Z docker-latex bash -c "make build && make clean"
docker run -ti -v ${PWD}:/master-thesis:Z docker-latex bash -c "make -C presentation && make -C presentation clean"

Now the diploma scientific leader could not just see my changes in the code, but also a detailed version of the document in PDF format.

Releases on GitHub

After I completed my diploma, I decided to share the template with the community. I decided to prettify README file at first, because this is the face of the project. The person who found my project on the Internet should read the file README without difficulty to figure out how to build the project and what to do with it.

README.md

Soon I will have to write the third diploma and I think that my approach to writing it will not change at all and I will spend quite a tiny amount of time on its design. Considering that I migrated from Linux to Mac OS, the transition will be absolutely painless, as there is a Docker.

Key takeaways

The usual interest of LaTeX allowed me to dive a bit more into this area:

  • got some practice with LaTeX, which later helped save time when creating documents and presentations
  • gained experience when working with git and GitHub, while working with these pet projects
  • used to practice things like Docker and TravisCI, which gave me a good push when diving into DevOps
  • learned how to draw up my pet projects

Good luck with your diplomas!

P.S My english not so good but I’m working on it. 💪