Bootstrapping your next LaTeX project

The process of setting up a new L^aT_eX project is made up of many manual steps, resulting in a patchwork that already from the start is not exercisable nor complete. In this post we will see how we can construct a solid starting point with a single command. This is part of a series to create the perfect open science git repository.

Introduction

Setting up a new L^aT_eX project is usually a boring process where I do manual repetitive steps such as creating a directory structure, add file stubs, copy the Makefile from some old project, and more.

I like to use git for version control of L^aT_eX documents, so setting up a git repository is an important step. I do this even if I am working alone on a project. Version control allows me to track my progress, have a backup, and make sure the document is completely reproducible from raw data. The principle of Reproducible Research (Buckheit & Donoho, 1995; Claerbout & Karrenbach, 1992; Association for Computing Machinery (ACM), n.d.) is to make data and computer code available for others to analyze and criticize.

A good open source repository is exercisable and complete (Monperrus, 2018; Association for Computing Machinery (ACM), n.d.). This means that it must be possible to fully reproduce the document, down to the last pixel, from running a single script in the repository. In How to annoy your co-authors: a Gitlab CI pipeline for L^aT_eX we took a look at this can be done - but there were many manual steps which we will automate in this post.

Here are a few things I always do at the start of a new L^aT_eX project.

Create a directory structure (for chapters, figures, data, bibliography, …),
Add a .gitignore default for L^aT_eX;
Create a main.tex-file from a L^aT_eX template, usually from a conference template;
Populate said file with author, working title;
Initialize git locally;
Create remote git repository on Gitlab, or a Gitlab CE instance;
Add a Makefile, configure it to use the compiler that the template dictates;
Add a .gitlab-ci.yml (see How to annoy your co-authors: a Gitlab CI pipeline for L^aT_eX);
Create a Sublime project;
Add a README.md with some build instructions for my co-authors and
Perform a test compilation of the entire project.

Using a project template

What if we can run a single command to set up a new project? For this we can use [cookiecutter](https://github.com/cookiecutter/cookiecutter) (Roy Greenfeld et al., 2020). cookiecutter is a command-line utility that creates projects from cookiecutters which are project templates.

Using a cookiecutter is easy. We can just run

1
cookiecutter gl:martisak/latex-template

Running cookiecutter

You will need a Gitlab account. Then you need to add these environment variables, for example by adding this to your .zshrc. Read more on how to create a private Gitlab token.

1
2
3
export GITLAB_API_PRIVATE_TOKEN=<your private token>
export GITLAB_API_USERNAME=<your username>
export GITLAB_URL=gitlab.com

Of course, some fields will always be the same (such as your name), so we can add our defaults to ~/.cookiecutterrc.

1
2
3
4
5
6
7
8
default_context:
    full_name: "Martin Isaksson"
    email: "m@cyberdyne.se"
    gitlab_username: "martisak"
    affiliation: "Cyberdyne Systems"
    department: "AI lab"
    paper_title: "Lorem ipsum"
cookiecutters_dir: "~/.cookiecutters/"

After you have run this cookiecutter template, you will have a working directory that looks like this.

├── Gemfile                         # For the test stage
├── Gemfile.lock                    # For the test stage
├── Makefile                        # For building
├── README.md                       # A stub README
├── chapters
│   ├── conclusion.tex              # A chapter in L^aT_eX
│   └── introduction.tex            # A chapter in L^aT_eX
├── figures
│   ├── Makefile                    # A Makefile for building the figures
│   ├── example.py                  # Python code for plotting
│   └── requirements.txt            # Requirements for the figure stage
├── lorem-ipsum.sublime-project     # A Sublime project file
├── lorem-ipsum.tex                 # This is the main L^aT_eX file
├── references
│   └── main.bib                    # References in bibtex
└── spec
    └── pdf_spec.rb                 # For the test stage

We see a lot of auxiliary files for testing and for setting up a Sublime project. If you have a better directory structure, feel free to fork my cookiecutter and make it better!

There are many existing cookiecutters for creating L^aT_eX documents. However, I didn’t find one that fitted my needs, so I made my own.

Yeoman (Osmani et al., 2020) provides another generator ecosystem, is language agnostic and can be used to generate any kind of scaffolding. However, since it is Node.js-based it could be argued that it is more geared towards web development. It is very extensible and it is easy to create custom templates, assuming knowledge of Node.js.

An interesting feature of Yeoman generators is that it allows for sub-generators. These can be used for example to generate new chapters in our documents.

Conclusion

So now we have a good starting point that you can use for your awesome next paper — all you need to do is fill in the blanks.

A remaining manual step is to find and copy the L^aT_eX template. If you always use the same template, this can be included in the cookiecutter template. In a future post we will look into how to use Pandoc and Markdown which will make choosing and switching templates easier.

References

Buckheit, J. B., & Donoho, D. L. (1995). Wavelab and reproducible research. In Wavelets and statistics (pp. 55–81). Springer.
Claerbout, J. F., & Karrenbach, M. (1992). Electronic documents give reproducible research a new meaning. In SEG Technical Program Expanded Abstracts 1992 (pp. 601–604). Society of Exploration Geophysicists. https://doi.org/10.1190/1.1822162
Association for Computing Machinery (ACM). Artifact Review and Badging. https://www.acm.org/publications/policies/artifact-review-badging
Monperrus, M. (2018). How to make a good open-science repository? https://researchdata.springernature.com/users/336958-martin-monperrus/posts/57389-how-to-make-a-good-open-science-repository
Roy Greenfeld, A., Roy Greenfeld, D., & Pierzina, R. (2020). cookiecutter. https://cookiecutter.readthedocs.io/
Osmani, A., Verschaeve, A., Ford, B., Monge, E., Bidelman, E., Ros, F., Hm, H., Moon, J., Mårtensson, K., Marohnić, M., Dara, M., Kühnel, M., Daniel, M., Hartig, P., Irish, P., Kumar, R. S., Boudrias, S., Sorhus, S., Sawchuk, S., & Gascon, U. (2020). Yeoman. https://yeoman.io/

Suggested citation

If you would like to cite this work, here is a suggested citation in BibTeX format.

@misc{isaksson_2020,
  author="Isaksson, Martin",
  title={{Martin's blog --- Bootstrapping your next LaTeX project}},
  year=2020,
  url=https://blog.martisak.se/2020/07/23/bootstrapping-your-next-latex-project/,
  note = "[Online; accessed 2024-10-03]"
}

Revisions

27 Jul 2023 - Change table-of-contents
23 Jul 2020 - Add new cookiecutter post

Bootstrapping your next LaTeX project

Categories

Tags

Table of contents

Introduction

Using a project template

Conclusion

References

Suggested citation

Revisions

Categories

Tags

Table of contents

Introduction

Using a project template

Related work

Conclusion

References

Suggested citation

Revisions