README.md 4.11 KB
Newer Older
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
1
# LaTeX Kick-Start
2

Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
3 4 5
You want to quickly set up your LaTeX-based project such that
* [SSOT (Single Source of Truth)](https://en.wikipedia.org/wiki/Single_source_of_truth) is guaranteed,
* collaborators can seamlessly work together through [git](https://xkcd.com/1597/),
6
* your PDF-product is [continuously delivered](https://en.wikipedia.org/wiki/Continuous_delivery)?
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
7

8 9 10
Sounds like you should [*kick-start*](https://dictionary.cambridge.org/dictionary/english/kick-start) your project ASAP. 

The following should not take longer than 5 minutes to set up.
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
11 12 13

## Steps to Kick-Start

14 15 16 17
Start with (1a) if you want to kick-start an existing project.

Start with (1b) if you don't have a GitLab project to kick-start. 

18
### (1a) Import `.gitlab-ci.yml` Configuration File into Your Existing GitLab Project
19 20 21

* Go to your GitLab project main page
* Click on `Set up CI/CD`
22
* Create the file [`.gitlab-ci.yml`](https://docs.gitlab.com/ee/ci/yaml/gitlab_ci_yaml.html) with the following content:
23 24 25 26 27 28 29 30 31 32 33
```yaml
image: registry.gitlab.com/islandoftex/images/texlive:latest

build:
  script:
    - latexmk -pdf main.tex
  artifacts:
    paths:
      - main.pdf
```
* If your main TeXfile is not called `main.tex` but `my-tex-file.tex`, replace all occurrences of `main` in the above snippet by `my-tex-file`
34 35 36 37 38 39 40 41 42
* If your main TeXfile does not reside in the base directory but in a subfolder `my-subfolder`, modify the `build` portion of the `.gitlab-ci.yml`-file as follows:
```yaml
  script:
    - cd my-subfolder
    - latexmk -pdf main.tex
  artifacts:
    paths:
      - my-subfolder/main.pdf
```
43 44 45
* Proceed with Step (II).

### (1b) `Import` this Project into Your TUHH-GitLab Namespace
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
46 47 48 49 50 51 52 53 54 55 56 57 58 59

* Log into your TUHH-GitLab account at [`https://collaborating.tuhh.de/users/sign_in`](https://collaborating.tuhh.de/users/sign_in)
* Click on `New Project` or visit [`https://collaborating.tuhh.de/projects/new`](https://collaborating.tuhh.de/projects/new)
* Select the tile **Import project**
* Select **Import project from** `Repo by URL`
* Under **Git repository URL** paste this *Clone with HTTPS*-URL 
```
https://collaborating.tuhh.de/cfg0846/latex-kick-start.git
```
* Set a suitable **Project Name**
* Choose the **Visibility Level** 
* Click on `Create Project`
* Go back to the project dashboard or visit [`https://collaborating.tuhh.de/dashboard/projects`](https://collaborating.tuhh.de/dashboard/projects)
* Select the project you just created
60 61 62
* Proceed with step (2)

### (2) Activate GitLab Runner 
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
63 64 65 66 67

* Go to `Settings - CI/CD`
* Locate **Runners** and click `Expand`
* Under **Shared runners** click `Enable shared runners`

68
### (3) Add a Badge for Downloading Your Product
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
69 70 71

* Go to `Settings - General`
* Locate **Badges** and click `Expand`
72
* **Name** your badge
73
* Paste the following URL under **Link**
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
74 75 76
```
https://collaborating.tuhh.de/%{project_path}/-/jobs/artifacts/master/raw/main.pdf?job=build
```
77
* If you started out with your own repository (Step 1a), replace `main` accordingly
78
* Paste the following URL under **Badge image URL**
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
79 80 81
```
https://img.shields.io/badge/Download-PDF-brightgreen
```
82
* The badge should now appear on your projects main page and look like this one:
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
83

84
![](https://img.shields.io/badge/Download-PDF-brightgreen)
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
85

86
Note that the badge does not point to a product yet but it will, eventually, after you commited a change to this repository. 
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
87

88
#### You just finished kick-starting your project. Enjoy the ride!
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
89

90
## Credits and Further Resources
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
91 92

* [A Cookbook for LaTeX with git](https://collaborating.tuhh.de/alex/latex-git-cookbook) by Alexander Povel (@alex) -- extensive resource if you want to push your project to the next level.
93
* [gitignore.io](https://gitignore.io) -- automatically created the [`.gitignore`](https://git-scm.com/docs/gitignore) file for this repo.
Fabian Nuraddin Alexander Gabel's avatar
Fabian Nuraddin Alexander Gabel committed
94 95
* [Island of TeX](https://gitlab.com/islandoftex) -- nice repo with further utilities. They also provide the TeX Live [Docker image](https://gitlab.com/islandoftex/images/texlive) that is used by our pipeline.
* [shields.io](https://shields.io/) -- used to create the download badge.
96
* [TeXtidote](https://github.com/sylvainhalle/textidote) -- a correction tool (spelling and grammar) for LaTeX documents and other formats
97