diff --git a/README.md b/README.md index 89beaa8f5201c2f8ac7825832e0846914b3bb41b..3b9dfc2437d982f0ab44957c6cb3241920c6647d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,79 @@ Change to Document Title Here ============================= +Continuous Integration +---------------------- + +In GitLab, projects can **automatically be built, tested and deployed**. In +general, this is called **continuous integration** (CI) and **continuous +deployment** (CD). Both together are abbreviated to **CI / CD** and this is +what you will see in the GitLab web interface. + +You define what the CI server should do in the `.gitlab-ci.yml` file. This +project template contains two stages: + +1. **check** to run the spell checker on all document sources +1. **deploy** to upload the built document to an iDiv [Nextcloud][idiv-nc] + share + +### Spell Checking + +Unfortunately, spell checking is still [a bit awkward][spell-check-issue]. The +problem is that the currently existing spell checking tools are not really well +integrated. See [this issue][spell-check-issue] for more information and +progress. + +If you think that the spell checker with its [current +limitations][spell-check-issue] is more of an annoyance than help, you can +disable it by removing the **check** stage from the `.gitlab-ci.yml` file. Once +the issues are fixed, you can simply re-enable it by reverting the commit. + +### Deployment to Nextcloud + +The **deploy** stage tries to upload the built document to an iDiv +[Nextcloud][idiv-nc] share. To make this work, you will need to set this up +first by following these steps: + +1. **log in to Nextcloud** + + Go to the iDiv [Nextcloud][idiv-nc] and log in. + +1. **create a new, empty folder** + + My recommendation is to create a top-level folder named **documents**. + Then, create a sub-folder named after your project, e.g. the document + title. + + Avoid spaces and use dashes or underscores instead! + +1. **share the folder** + + Click on the **share** icon of the folder. Click on the plus `+` icon next + to **Share link**. Check the **Password protect** box and set your + password. Then click the **Allow upload and editing** radio button. + + Finally, click on the **copy link to clipboard** icon. + +1. **CI settings** + + Go to your GitLab project. Go to **Settings**, **CI / CD** and expand the + **Variables** section. Add two variables: + + 1. `NEXTCLOUD_SHARE`, paste the share link you copied from Nextcloud. + Remove everything except the part after the last slash `/`, e.g. if + your link is: + + ``` + https://portal.idiv.de/nextcloud/index.php/s/aFgeXn5Ay9qffbd + ``` + + ... you only need the `aFgeXn5Ay9qffbd` part. + + 1. `NEXTCLOUD_PW`, with the password of the share. + + Make sure both variables are masked so the values will not show up in your + logs. + Building -------- @@ -33,6 +106,9 @@ build the template PDF, you need these dependencies: **Note:** On MS Windows, it might be helpful using [chocolatey][]. +[idiv-nc]: https://portal.idiv.de/nextcloud/ +[spell-check-issue]: https://git.idiv.de/templates/pandoc/issues/3 + [chocolatey]: https://chocolatey.org/ [git]: https://git-scm.com/downloads [graphviz]: https://graphviz.gitlab.io/download/