From 1f1964c96292e72980e2334725d7d3c8c17ee6db Mon Sep 17 00:00:00 2001
From: Remco de Boer <29308176+redeboer@users.noreply.github.com>
Date: Wed, 17 Aug 2022 17:27:49 +0200
Subject: [PATCH] DX!: build documentation on GitLab pages (#156)

* DOC: fix LaTeX rendering in `README.md`
* DX: automatically push to GitLab from main branch
---
 .cspell/this-project.txt             |  4 ++++
 .github/workflows/push-to-gitlab.yml | 20 ++++++++++++++++++++
 .gitlab-ci.yml                       | 22 ++++++++++++++++++++++
 README.md                            |  6 +++---
 docs/conf.py                         |  1 +
 5 files changed, 50 insertions(+), 3 deletions(-)
 create mode 100644 .github/workflows/push-to-gitlab.yml
 create mode 100644 .gitlab-ci.yml

diff --git a/.cspell/this-project.txt b/.cspell/this-project.txt
index af341fda..c676df01 100644
--- a/.cspell/this-project.txt
+++ b/.cspell/this-project.txt
@@ -1,5 +1,7 @@
 ComPWA
 Conda
+docnb
+dvipng
 heli
 ifhyphenaverage
 Mikhasenko
@@ -8,4 +10,6 @@ nbformat
 phsp
 PYTHONHASHSEED
 Remco
+texlive
 toctree
+venv
diff --git a/.github/workflows/push-to-gitlab.yml b/.github/workflows/push-to-gitlab.yml
new file mode 100644
index 00000000..7a379f6c
--- /dev/null
+++ b/.github/workflows/push-to-gitlab.yml
@@ -0,0 +1,20 @@
+name: Push to GitLab
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  push:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Push main branch to GitLab
+        run: |
+          git remote add gitlab "https://oauth2:${token}@gitlab.cern.ch/polarimetry/Lc2pKpi.git"
+          git push gitlab main
+        env:
+          token: ${{ secrets.GITLAB_TOKEN }}
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
new file mode 100644
index 00000000..ba86a91b
--- /dev/null
+++ b/.gitlab-ci.yml
@@ -0,0 +1,22 @@
+image: python:3.8
+
+pages:
+  only:
+    - main
+  before_script:
+    - apt-get update
+    - apt-get install -y cm-super dvipng texlive-latex-extra
+    - python3 -m pip install .[doc]
+    - wget -q https://julialang-s3.julialang.org/bin/linux/x64/1.7/julia-1.7.3-linux-x86_64.tar.gz
+    - tar xzf julia-1.7.3-linux-x86_64.tar.gz
+    - mv julia-1.7.3 /opt/
+    - ln -s /opt/julia-1.7.3/bin/julia /usr/local/bin/julia
+    - julia --project=./julia -e 'import Pkg; Pkg.instantiate()'
+  script:
+    - sphinx-build -nW --color --keep-going -b html docs/ public
+  variables:
+    EXECUTE_NB: "YES"
+    EXECUTE_PLUTO: "YES"
+  artifacts:
+    paths:
+      - public
diff --git a/README.md b/README.md
index d1bd75dc..ba65004b 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,9 @@
 
 [![GPLv3+ license](https://img.shields.io/badge/License-GPLv3+-blue.svg)](https://www.gnu.org/licenses/gpl-3.0-standalone.html)
 
-This repository a symbolic amplitude model for the decay $\Lambda^+_c \to p \pi^+ K^-$ that is aligned with [Dalitz-plot decomposition](https://journals.aps.org/prd/abstract/10.1103/PhysRevD.101.034033) and computes an align polarimeter vector field $\vec\alpha$. Helicity couplings and other parameter values are taken from [_Amplitude analysis of the $\Lambda^+_c \to p K^- \pi^+$ decay and $\Lambda^+_c$ baryon polarization measurement in semileptonic beauty hadron decays_](https://inspirehep.net/literature/2132745) (2022) by the LHCb Collaboration and its [supplementary material](https://cds.cern.ch/record/2824328/files).
+This repository a symbolic amplitude model for the decay $\Lambda^+_c \to p \pi^+ K^-$ that is aligned with [Dalitz-plot decomposition](https://journals.aps.org/prd/abstract/10.1103/PhysRevD.101.034033) and computes an align polarimeter vector field $\vec\alpha$. Helicity couplings and other parameter values are taken from a recent study by the LHCb Collaboration[^1] and its [supplementary material](https://cds.cern.ch/record/2824328/files).
+
+[^1]: Amplitude analysis of the $\Lambda^+_c \to p K^- \pi^+$ decay and $\Lambda^+_c$ baryon polarization measurement in semileptonic beauty hadron decays (2022) [[link]](https://inspirehep.net/literature/2132745)
 
 ## Installation
 
@@ -33,8 +35,6 @@ julia --project=./julia -e 'import Pkg; Pkg.instantiate()'
 
 To build the documentation, you need to install LaTeX and some additional fonts. In Ubuntu, this can be done with:
 
-<!-- cspell:ignore docnb dvipng texlive -->
-
 ```shell
 sudo apt install -y cm-super dvipng texlive-latex-extra
 ```
diff --git a/docs/conf.py b/docs/conf.py
index 7e2a03cc..c8b9db74 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -198,6 +198,7 @@ def generate_api() -> None:
 }
 nb_execution_allow_errors = False
 nb_execution_mode = get_execution_mode()
+nb_execution_show_tb = True
 nb_execution_timeout = -1
 nb_output_stderr = "show"
 nb_render_markdown_format = "myst"