Как я диплом в LaTeX писал с GitHub, Docker и TravisCI29.09.2018 12:49

Еще со времен обучения в университете я использовал LaTeX для оформления лабораторных и курсовых работ. Познакомился впервые с LaTeX я на Coursera, на курсе «Документы и презентации в LaTeX».

В этой заметке я расскажу, как я писал диплом с помощью LaTeX, GitHub, Docker и TravisCI.

Но зачем?

Предисловие

Мой путь редактирования и создания документов начался с Microsoft Word, наверное как и у многих, когда я стал использовать Linux я без труда стал использовать сначала OpenOffice, а потом LibreOffice, который в моих задачах не уступал по функционалу первому. Немного больно было, когда написав какой-нибудь реферат в компьютерном зале библиотеки, несешь его на распечатку на админский компьютер с Microsoft Word, а у тебя слетает все форматирование и перед распечаткой нужно было пройтись по всему документу. В то школьное время мне никто не объяснил того, что можно сохранить документ в PDF и печатать где хочешь, это я уже сам узнал, когда учился в университете и нужно было печатать документы чуть ли не каждый день.

Вернемся к LaTeX, до его использования, все что я слышал о LaTeX, это то, что с его помощью пишут статьи в научные журналы из-за того, что он очень удобен для работы с формулами. Те кто думают так же, рекомендую посмотреть курс на Coursera, возможно он изменит ваше мнение, мне например он очень понравился.

Hello, World на LaTeX:

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

Кстати с помощью LaTeX можно делать и презентации. Вот тут можно посмотреть множество примеров как могут выглядеть эти презентации.

Бакалаврский диплом с LaTeX

К концу третьего курса я уже активно использовал LaTeX для оформления практически всех документов, решено было с его помощью писать и бакалаврский диплом.

Поначалу я использовал LaTeXila в качестве IDE, в котором сборка проекта осуществлялась одной кнопкой, можно было подключить спеллчекер, но он у меня иногда вылетал и я стал использовать Sublime Text вместе с Makefile.

Пример Makefile:

all: build run

build:
    latexmk -xelatex \
    -synctex=1 main.tex

run:
    # Я использую xreader для просмотра PDF
    xreader main.pdf &

clean:
    rm *.aux \
    *.fdb_latexmk \
    *.fls \
    *.log \
    *.out \
    *.synctex.gz \
    *.toc

Все исходники хранил в git, для удобства коллаборации с научным руководителем использовал GitHub. Структура проекта была очень простой, в файл main.tex подключались преамбула и остальные главы, которые хранились в отдельном каталоге.

main.tex:

\documentclass[a4paper,14pt]{extarticle} % 14й шрифт
\input{inc/preamble} % Подключаем преамбулу

\begin{document}
\tableofcontents % Содержание 
\clearpage

\input{inc/0-intro} % Введение
\input{inc/1-pz} % Постановка задачи
...
\input{inc/0-bibliography} % Библиографический список

\input{inc/a-app} % Исходный код скрипта DDoS Deflate
\input{inc/b-app} % Руководство пользователя
\includepdf{act} % Акт внедрения
\end{document}

Описание всех стилей и форматирование находится в файле preamble.tex, который подключается в самом начале документа.

Очень удобно было не заботиться о форматировании содержания, библиографического списка и прочих частей диплома.

Содержание

Опишу свои плюсы при работе с LaTeX, по сравнению с WYSIWYG-редакторами на тот момент:

удобная версионируемость (вместо диплом.odt, диплом_01.01.2015.odt, диплом_исправл_печать.odt версионируемость в git и возможность откатиться на любой момент в истории)
при случайном нажатии чего-либо, верстка не слетает (у меня такое бывало в WYSIWYG)
гибкие настройки, которые не всегда доступны в WYSIWYG или они неочевидны
гомогенная среда для всего (исходники презентации лежат в том же репозитории, что и диплом)
возможность коллаборации, дипломный руководитель может смотреть в репозитории что изменилось со времен последней проверки
удобно использовать как шаблон для множества различных документов
удобно включать такие вставки как исходный код например или дополнительные PDF-файлы

Вот пример того, как легко можно подключить в документ файл с исходным кодом (его можно раскрашивать как угодно, включать номера строк и много других интересных вещей):

\lstinputlisting[numbers=left]{inc/ddos-deflate/ddos.sh}

Подключенный исходный код в документ

Минус использования LaTeX для меня только один — нужно потратить время для того, чтобы отполировать это все до нужного результата. Я даже на мгновение захотел заморочиться, чтобы перерисовать все диаграммы и картинки нативным способом с помощью TikZ, но это требовало очень много времени, поэтому я спокойно рисовал свои картинки в Google Drawings и draw.io.

Успешно защитив бакалаврский диплом и получив некоторые знания по работе с git, GitHub, Makefile, гуглению по LaTeXStackExchange на английском, я забыл про диплом на пару лет, для того чтобы использовать свой шаблон для написания уже магистерского диплома.

Магистерский диплом

В то время когда я обучался в магистратуре, я уже стал увлекаться инструментами инженера, такими как Docker, стал практиковаться с инструментами Continuous Integration, изучать практики DevOps. Также мне было интересно красиво оформлять свои пет-опенсорс-проекты с красивыми README и прочими бейджами.

В целом, когда я приступил к написанию магистерского диплома, требования к оформлению не особо изменились, поэтому по факту я взял шаблон своего бакалаврского диплома и допилил по мелочи, например такие пункты как список иллюстративного материала, перечень сокращений и прочее. При защите бакалаврского диплома мы использовали плакаты размером A1, а в магистерском нам уже разрешили использовать презентации в виде слайдов, поэтому слайды я также верстал с помощью LaTeX и beamer.

Презентация сверстанная с помощью LaTeX и beamer

Я подумал, а почему бы не собирать при каждом коммите в репозиторий новый PDF с помощью CI, подключение GitHub к TravisCI заняло 10 минут. TravisCI не умеет напрямую работать с LaTeX, но зато прекрасно работает с Docker. Круто, подумал я, убью сразу несколько зайцев:

попрактикуюсь с написанием Dockerfile
смигрирую все латеховские пакеты в Docker (а их там немало и они довольно тяжелые)
попрактикуюсь с использованием TravisCI
помогу тем, кто вдруг когда-то захочет воспользоваться моим шаблоном на отличной от Linux ОС

Написание файла конфигурации для TravisCI, Dockerfile и редактирование Makefile заняло не очень много времени и получилось вполне себе удобно:

Часть Makefile для запуска сборки проекта в 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"

Теперь дипломный руководитель мог не просто посмотреть мои изменения в коде, но и как оно выглядит в сверстанном виде.

Релизы

Оформив диплом в приемлимом для себя виде, я решил поделиться шаблоном с сообществом, по аналогии со своим бакалаврским. Решено было красиво оформить README-файл репозитория, ведь это лицо проекта. Человек который нашел твой проект в интернете должен по файлу README сразу же без труда разобраться как собрать проект и что с ним делать.

Файл README.md

Скоро мне предстоит писать третий диплом и я думаю, что мой подход к его написанию ничуть не изменится и на его оформление я потрачу совсем мизерное количество времени.

Итоги

Обычная заинтересованность LaTeX’ом позволила мне немного больше погрузиться в эту сферу:

набить руку при работе с LaTeX, что в дальнейшем помогло сэкономить время при создании документов и презентаций
набрался опыта при работе с git и GitHub, пока работал с этими пет-проектами
использовал на практике такие вещи как Docker и TravisCI, что дало мне хороший толчок при погружении в DevOps
научился аккуратно оформлять свои пет-проекты

Ответы на потенциальные вопросы

Зачем хранишь в репозитории PDF-файлы?

Исключительно для того, чтобы человек, который зашел в репозиторий, мог не только посмотреть исходники, но и увидеть результат всего этого.

Не до конца автоматизированы многие вещи, например библиография

Согласен, по тем или иным причинам я не стал более глубоко докапываться до этого, возможно те, у кого сотни источников использованной литературы будет больно.

Соответствует ли шаблон ГОСТ/ДСТУ?

Я руководствовался исключительно требованиями нормоконтроллера, скорее всего у каждого была/будет такая ситуация.