From 09a8720f1174d11d9069546b4a10ece3ccaf467e Mon Sep 17 00:00:00 2001
From: Remco de Boer <redeboer@gmx.com>
Date: Thu, 8 Apr 2021 13:32:02 +0200
Subject: [PATCH] feat: add PDG listing and review role

---
 docs/conf.py            | 43 +++++++++++++++++++++++++++++++++++------
 docs/theory/glossary.md | 26 +++++++++++++------------
 2 files changed, 51 insertions(+), 18 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index c7226304..d639932e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -208,20 +208,51 @@
     "repository_branch": html_theme_options["repository_branch"],
 }
 
-# Add roles to simplify external linnks
+# Add roles to simplify external links
+pdg_version = 2020
+
+
 def setup(app: Sphinx):
     app.add_role(
-        "wiki", autolink("https://en.wikipedia.org/wiki/%s", {"_": " "})
+        "wiki",
+        wikilink("https://en.wikipedia.org/wiki/%s"),
+    )
+    app.add_role(
+        "pdg-listing",
+        role=pdglink(
+            f"https://pdg.lbl.gov/{pdg_version}/listings/rpp{pdg_version}-list-%s.pdf"
+        ),
     )
+    app.add_role(
+        "pdg-review",
+        role=pdglink(
+            f"https://pdg.lbl.gov/{pdg_version}/reviews/rpp{pdg_version}-rev-%s.pdf"
+        ),
+    )
+
+
+def pdglink(pattern: str):
+    def role(
+        name, rawtext: str, text: str, lineno, inliner, options={}, content=[]
+    ):
+        label = text
+        label = f"§ {label}"
+        url = text
+        url = url.lower()
+        url = url.replace(" ", "-")
+        url = pattern % (url,)
+        node = nodes.reference(rawtext, label, refuri=url, **options)
+        return [node], []
+
+    return role
 
 
-def autolink(pattern: str, replace_mapping: Dict[str, str]):
+def wikilink(pattern: str):
     def role(
-        name, rawtext, text: str, lineno, inliner, options={}, content=[]
+        name, rawtext: str, text: str, lineno, inliner, options={}, content=[]
     ):
         output_text = text
-        for search, replace in replace_mapping.items():
-            output_text = output_text.replace(search, replace)
+        output_text = output_text.replace("_", " ")
         url = pattern % (text,)
         node = nodes.reference(rawtext, output_text, refuri=url, **options)
         return [node], []
diff --git a/docs/theory/glossary.md b/docs/theory/glossary.md
index 17adfb64..74364221 100644
--- a/docs/theory/glossary.md
+++ b/docs/theory/glossary.md
@@ -20,19 +20,20 @@ K-matrix
   A real, symmetric and hermitian operator that is defined from the
   {term}`T-matrix` through $K^{-1} = T^{-1} + iI$. See
   {cite}`badalyanResonancesCoupledChannels1982,chungPartialWaveAnalysis1995`
-  and {cite}`particledatagroupReviewParticlePhysics2020`, Section 49
-  (Resonances).
+  and {cite}`particledatagroupReviewParticlePhysics2020`
+  ({pdg-review}`Resonances`).
 
 P-vector
 
   First described in {cite}`aitchisonMatrixFormalismOverlapping1972`. See also
   {cite}`chungPartialWaveAnalysis1995` and
-  {cite}`particledatagroupReviewParticlePhysics2020`, Section 49 (Resonances).
+  {cite}`particledatagroupReviewParticlePhysics2020` ({pdg-review}`Resonances`).
 
 Q-vector
 
   See {cite}`chungPartialWaveAnalysis1995` and
-  {cite}`particledatagroupReviewParticlePhysics2020`, Section 49 (Resonances).
+  {cite}`particledatagroupReviewParticlePhysics2020`
+  ({pdg-review}`Resonances`).
 
 S-matrix
 scattering operator
@@ -83,8 +84,8 @@ formation experiment
   Here, $R$ is the resonance in which one is often interested in
   {term}`hadron spectroscopy`.
 
-  See {cite}`particledatagroupReviewParticlePhysics2020`, Section 49
-  (Resonances). Related: {term}`production experiment`.
+  See {cite}`particledatagroupReviewParticlePhysics2020`
+  ({pdg-review}`Resonances`). Related: {term}`production experiment`.
 
 hadron
 
@@ -125,13 +126,13 @@ spectator particle
   case is comparable to a {term}`formation experiment`, while the second
   represents a decay process of particle $Z$.
 
-  See {cite}`particledatagroupReviewParticlePhysics2020`, Section 49
-  (Resonances).
+  See {cite}`particledatagroupReviewParticlePhysics2020`
+  ({pdg-review}`Resonances`).
 
 Quantum Chromodynamics (QCD)
 
   The theory that describes the strong force on the most fundamental level. See
-  [PDG review on QCD](https://pdg.lbl.gov/2020/reviews/rpp2020-rev-qcd.pdf).
+  {cite}`particledatagroupReviewParticlePhysics2020` ({pdg-review}`qcd`).
 
 quark
 
@@ -141,12 +142,13 @@ Quark Constituent Model (QCM)
 
   Model with which to describe and categorize matter constituted of quarks
   (i.e. {term}`hadrons <hadron>`). See
-  {cite}`particledatagroupReviewParticlePhysics2020`, Section 15.
+  {cite}`particledatagroupReviewParticlePhysics2020`
+  ({pdg-review}`Quark Model`).
 
 resonance
 
-  See {cite}`particledatagroupReviewParticlePhysics2020`, Section 49
-  (Resonances).
+  See {cite}`particledatagroupReviewParticlePhysics2020`
+  ({pdg-review}`Resonances`).
 
 Standard Model