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

@@ -1,5 +1,7 @@
 ComPWA
 Conda
+docnb
+dvipng
 heli
 ifhyphenaverage
 Mikhasenko
@@ -8,4 +10,6 @@ nbformat
 phsp
 PYTHONHASHSEED
 Remco
+texlive
 toctree
+venv

.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 }}

.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

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
 ```

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"