DOC: add overview of links related to publication (#273)

* DOC: add arXiv badge
* DOC: add Zenodo badge
* DOC: add caption to main `toctree`
* DOC: add LHCb logo
* DOC: add overview of main features
* DOC: collect links related to publication on welcome page
* DOC: import abstract to welcome page
* DOC: list Figure numbers next to download links
  Actually `setup.cfg` should list:
  ```ini
  [options.extras_require]
  doc =
      ...
      myst-parser >0.16.0  # field lists
      ...
  ```
  but this has not been done in the current PR as to avoid the constraint
  files from being updated.
* DOC: show only first level in left sidebar
  Looks better with the external links
* DOC: sync HTML short title with paper title
* FIX: add missing verb for downloading images

.cspell.json

@@ -121,16 +121,20 @@
     "isfinite",
     "lc2pkpi",
     "mathbf",
+    "mathrm",
     "mystnb",
     "nbsp",
     "numref",
+    "octicon",
     "prereleased",
     "rgba",
     "shared_yaxes",
     "tableofcontents",
     "textbf",
     "tickvals",
+    "twiki",
     "unsrt",
+    "viewauth",
     "xaxes",
     "xaxis",
     "xshift",

.cspell/physics.txt

@@ -7,10 +7,12 @@ Flatté
 Gordan
 helicities
 helicity
+Indico
 JPAC
 Källén
 lineshape
 lineshapes
 ls
 SymPy
 Weisskopf
+Zenodo

README.md

@@ -2,6 +2,8 @@
 
 <!-- cspell:ignore semileptonic -->
 
+[![10.48550/arXiv.2301.07010](https://zenodo.org/badge/doi/10.48550/arXiv.2301.07010.svg)](https://doi.org/10.48550/arXiv.2301.07010)
+[![10.5281/zenodo.7544989](https://zenodo.org/badge/doi/10.5281/zenodo.7544989.svg)](https://doi.org/10.5281/zenodo.7544989)
 [![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 a recent study by the LHCb Collaboration[^1] and its [supplementary material](https://cds.cern.ch/record/2824328/files).

docs/.gitignore

@@ -2,3 +2,5 @@
 *.json
 *.zip
 /api/
+
+!_static/lhcb-logo.svg

docs/conf.py

@@ -16,24 +16,30 @@
 
 
 def download_paper_figures() -> str:
-    files = [
-        "_static/images/total-polarimetry-field-watermark.svg",
-        "_static/images/polarimetry-field-L1520-unaligned-watermark.svg",
-        "_static/images/polarimetry-field-L1520-aligned-watermark.svg",
-        "_static/images/polarimetry-field-norm-uncertainties-watermark.png",
-    ]
-    for file in files:
-        if not os.path.exists(file):
-            print_missing_file_warning(file)
+    figures = {
+        "2": "_static/images/total-polarimetry-field-watermark.svg",
+        "3a": "_static/images/polarimetry-field-L1520-unaligned-watermark.svg",
+        "3b": "_static/images/polarimetry-field-L1520-aligned-watermark.svg",
+        "4": "_static/images/polarimetry-field-norm-uncertainties-watermark.png",
+    }
+    for path in figures.values():
+        if not os.path.exists(path):
+            print_missing_file_warning(path)
             return ""
-    list_of_figures = indent("\n".join(_to_download_link(f) for f in files), "    - ")
+    list_of_figures = indent(
+        "\n".join(
+            f":Figure {name}: {_to_download_link(path)}"
+            for name, path in figures.items()
+        ),
+        4 * " ",
+    )
     src = f"""
     ::::{{only}} html
     :::{{tip}}
     Figures for the paper can be downloaded here:
     {list_of_figures.strip()}
 
-    All other exported figures can be [here](./_static/images/).
+    All other exported figures can be found [here](./_static/images/).
     :::
     ::::
     """
@@ -142,13 +148,10 @@ def get_link_to_single_pdf() -> str:
         shutil.copy(build_file, embedded_file)
     if os.path.exists(embedded_file):
         src = f"""
-        ::::{{only}} html
-        :::{{button-link}} {embedded_file}
-        :color: primary
-        :shadow:
-        Download this website as a **report**
+        :::{{grid-item-card}} {{octicon}}`download` Download this website as a single PDF file
+        :columns: 12
+        :link: {embedded_file}
         :::
-        ::::
         """
         return dedent(src)
     print(f"\033[91;1mSingle PDF has not yet been built.\033[0m")
@@ -224,6 +227,7 @@ def print_missing_file_warning(filename: str) -> None:
     # https://github.com/requirejs/requirejs/tags
     "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js",
 ]
+html_logo = "_static/lhcb-logo.svg"
 html_sourcelink_suffix = ""
 html_static_path = ["_static"]
 html_theme = "sphinx_book_theme"
@@ -241,13 +245,13 @@ def print_missing_file_warning(filename: str) -> None:
     "path_to_docs": "docs",
     "repository_url": "https://github.com/ComPWA/polarimetry",
     "repository_branch": "main",
-    "show_navbar_depth": 2,
+    "show_navbar_depth": 1,
     "show_toc_level": 2,
     "use_repository_button": True,
     "use_edit_page_button": True,
     "use_issues_button": True,
 }
-html_title = "Polarimetry Λ<sub>c</sub> → p K π"
+html_title = "Λ<sub>c</sub>&nbsp;→&nbsp;p&nbsp;K&nbsp;π polarimetry"
 intersphinx_mapping = {
     "IPython": ("https://ipython.readthedocs.io/en/stable", None),
     "ampform": ("https://ampform.readthedocs.io/en/stable", None),
@@ -309,6 +313,7 @@ def print_missing_file_warning(filename: str) -> None:
 myst_enable_extensions = [
     "colon_fence",
     "dollarmath",
+    "fieldlist",
     "html_image",
     "substitution",
 ]

docs/index.md

@@ -5,20 +5,93 @@ myst:
 
 # Polarimetry in Λ<sub>c</sub> → p π K
 
+[![10.48550/arXiv.2301.07010](https://zenodo.org/badge/doi/10.48550/arXiv.2301.07010.svg)](https://doi.org/10.48550/arXiv.2301.07010)
+[![10.5281/zenodo.7544989](https://zenodo.org/badge/doi/10.5281/zenodo.7544989.svg)](https://doi.org/10.5281/zenodo.7544989)
+
+<!-- cspell:disable -->
+
+:::{card} $\Lambda^+_\mathrm{c}$ polarimetry using the dominant hadronic mode
+:link: https://arxiv.org/abs/2301.07010
+
+The polarimeter vector field for multibody decays of a spin-half baryon is introduced as a generalisation of the baryon asymmetry parameters. Using a recent amplitude analysis of the $\Lambda^+_\mathrm{c} \to p K^- \pi^+$ decay performed at the LHCb experiment, we compute the distribution of the kinematic-dependent polarimeter vector for this process in the space of Mandelstam variables to express the polarised decay rate in a model-agnostic form. The obtained representation can facilitate polarisation measurements of the $\Lambda^+_\mathrm{c}$ baryon and eases inclusion of the $\Lambda^+_\mathrm{c} \to p K^- \pi^+$ decay mode in hadronic amplitude analyses.
+
+<!-- cspell:enable -->
+
+:::
+
+:::::{only} html
+::::{grid} 1 2 2 2
+:margin: 4 4 0 0
+:gutter: 1
+
+:::{grid-item-card} {material-regular}`functions` Symbolic expressions
+:link: amplitude-model
+:link-type: doc
+
+Compute the amplitude model over large data samples with symbolic expressions.
+:::
+
+:::{grid-item-card} {octicon}`file-code` JSON grids
+:link: exported-distributions
+:link-type: ref
+
+Reuse the computed polarimeter field in any amplitude analysis involving $\Lambda_\mathrm{c}^+$.
+:::
+
+:::{grid-item-card} {material-regular}`ads_click` Inspect interactively
+:link: appendix/widget
+:link-type: doc
+
+Investigate how parameters in the amplitude model affect the polarimeter field.
+:::
+
+:::{grid-item-card} {octicon}`book` Compute polarization
+:link: zz.polarization-fit
+:link-type: doc
+
+Learn how to determine the polarization vector using the polarimeter field.
+:::
+
 {{ DOWNLOAD_SINGLE_PDF }}
+::::
+:::::
+
+This webpage shows all analysis results that led to the publication of [LHCb-PAPER-2022-044](https://cds.cern.ch/record/2838694). More information on this publication can be found on the following pages:
+
+- Publication on arXiv: [arXiv:2301.07010](https://arxiv.org/abs/2301.07010)
+- Record on CDS: [cds.cern.ch/record/2838694](https://cds.cern.ch/record/2838694)
+- Record for the source code on Zenodo: [10.5281/zenodo.7544989](https://doi.org/10.5281/zenodo.7544989)
+- Frozen documentation on GitLab Pages: [lc2pkpi-polarimetry.docs.cern.ch](https://lc2pkpi-polarimetry.docs.cern.ch)
+- Frozen repository on CERN GitLab: [gitlab.cern.ch/polarimetry/Lc2pKpi](https://gitlab.cern.ch/polarimetry/Lc2pKpi)
+- Active repository on GitHub containing discussions: [github.com/ComPWA/polarimetry](https://github.com/ComPWA/polarimetry)
+
+:::{admonition} Behind SSO login (LHCb members only)
+:class: toggle
 
-:::{only} latex
+- LHCb TWiki page: [twiki.cern.ch/twiki/bin/viewauth/LHCbPhysics/PolarimetryLc2pKpi](https://twiki.cern.ch/twiki/bin/viewauth/LHCbPhysics/PolarimetryLc2pKpi)
+- Charm WG meeting: [indico.cern.ch/event/1187317](https://indico.cern.ch/event/1187317)
+- RC approval presentation: [indico.cern.ch/event/1213570](https://indico.cern.ch/event/1213570)
+- Silent approval to submit: [indico.cern.ch/event/1242323](https://indico.cern.ch/event/1242323)
+
+:::
+
+::::{only} latex
 
 <!-- cspell:ignore lc2pkpi -->
 
+:::{note}
+
 This document is a PDF rendering of the supplemental material hosted behind SSO-login on [lc2pkpi‑polarimetry.docs.cern.ch](https://lc2pkpi-polarimetry.docs.cern.ch). Go to this webpage for a more extensive and interactive experience.
 
 :::
 
+::::
+
 <!-- cspell:ignore maxdepth -->
 
 ```{toctree}
 ---
+caption: Table of contents
 maxdepth: 2
 numbered:
 ---
@@ -33,6 +106,21 @@ references
 API <api/polarimetry>
 ```
 
+:::{only} html
+
+```{toctree}
+---
+caption: External links
+hidden:
+---
+arXiv:2301.07010 <https://arxiv.org/abs/2301.07010>
+ComPWA <https://compwa-org.readthedocs.io>
+GitHub (active) <https://github.com/ComPWA/polarimetry>
+CERN GitLab (frozen) <https://gitlab.cern.ch/polarimetry/Lc2pKpi>
+```
+
+:::
+
 {{ LINK_TO_JULIA_PAGES }}
 
 {{ DOWNLOAD_PAPER_FIGURES }}

docs/uncertainties.ipynb

@@ -2260,6 +2260,8 @@
     "A potential explanation for the $xz$-correlation may be found in Section {ref}`alpha-xz-correlations-per-resonance`.\n",
     ":::\n",
     "\n",
+    "(exported-distributions)=\n",
+    "\n",
     "## Exported distributions"
    ]
   },