Fix building issues, see PR #4 on starterkit-ci

CONTRIBUTING.md

@@ -55,10 +55,9 @@ You can see your local version by using a web-browser to navigate to `http://loc
 [gh-fork-pull]: https://reflectoring.io/github-fork-and-pull/
 
 
-```eval_rst
-.. toctree::
-    :hidden:
+```{toctree}
+:hidden:
 
-    CONDUCT.md
-    LICENSE.md
+CONDUCT.md
+LICENSE.md
 ```

README.md

@@ -1,33 +1,39 @@
 # The LHCb Starterkit lessons ![Build Status](https://github.com/lhcb/starterkit-lessons/actions/workflows/build.yml/badge.svg)
 
+
 These are the lessons historically taught during the [LHCb Starterkit][starterkit].
 These lessons focus on LHCb software from Runs 1 and 2. For Run 3, the software changed a lot and a [new set of Starterkit lessons][run3-starterkit] was written.
 If you'd like to join the next workshop, visit [the website][starterkit] to find out when that will how and how to sign up.
 
+
 If you'd just like to learn about how to use the LHCb software, [read on](first-analysis-steps/README.md)!
 
+
 [starterkit]: https://lhcb.github.io/starterkit
 [run3-starterkit]: https://lhcb-starterkit-run3.docs.cern.ch/
 [first-analysis-steps]: https://lhcb.github.io/starterkit-lessons/first-analysis-steps/
 
 
-```eval_rst
-.. toctree::
-    :maxdepth: 3
-    :includehidden:
-    :caption: Contents:
-
-    first-analysis-steps/README.md
-    second-analysis-steps/README.md
-    self-guided-lessons/README.md
-    CONTRIBUTING.md
+```{toctree}
+:maxdepth: 3
+:includehidden:
+:caption: Contents:
 
-.. toctree::
-    :maxdepth: 2
-    :includehidden:
-    :caption: External links:
 
-    interesting-links/analysis-essentials.md
-    LHCb Core documentation <https://cern.ch/lhcb-core-doc/>
-    LHCb glossary <https://lhcb.github.io/glossary/>
+first-analysis-steps/README
+second-analysis-steps/README
+self-guided-lessons/README
+CONTRIBUTING
 ```
+
+
+```{toctree}
+:maxdepth: 2
+:includehidden:
+:caption: External links:
+
+
+interesting-links/analysis-essentials
+LHCb Core documentation <https://cern.ch/lhcb-core-doc/>
+LHCb glossary <https://lhcb.github.io/glossary/>
+```

first-analysis-steps/README.md

@@ -13,33 +13,32 @@ The [analysis essentials course](https://hsf-training.github.io/analysis-essenti
 
 {% endprereq %}
 
-```eval_rst
-.. toctree::
-    :hidden:
-    :caption: Contents:
-
-    prerequisites.md
-    introduction-to-course.md
-    physics-at-lhcb.md
-    dataflow.md
-    run-2-data-flow.md
-    analysisflow.md
-    davinci.md
-    bookkeeping.md
-    files-from-grid.md
-    interactive-dst.md
-    minimal-dv-job.md
-    loki-functors.md
-    add-tupletools.md
-    decay-tree-fitter.md
-    analysis-productions.md
-    davinci-grid.md
-    split-jobs.md
-    ganga-data.md
-    eos-storage.md
-    lhcb-dev.md
-    dataflow-run3.md
-    asking-questions.md
-    ecgd.md
-    contributing-lesson.md
+```{toctree}
+:hidden:
+:caption: Contents:
+
+prerequisites.md
+introduction-to-course.md
+physics-at-lhcb.md
+dataflow.md
+run-2-data-flow.md
+analysisflow.md
+davinci.md
+bookkeeping.md
+files-from-grid.md
+interactive-dst.md
+minimal-dv-job.md
+loki-functors.md
+add-tupletools.md
+decay-tree-fitter.md
+analysis-productions.md
+davinci-grid.md
+split-jobs.md
+ganga-data.md
+eos-storage.md
+lhcb-dev.md
+dataflow-run3.md
+asking-questions.md
+ecgd.md
+contributing-lesson.md
 ```

first-analysis-steps/add-tupletools.md

@@ -164,7 +164,7 @@ To add LoKi-based leaves to the tree, we need to use the `LoKi::Hybrid::TupleToo
   1. Its *name*, specified in the `addTupleTool` call after a `/`.  This is 
      very useful (and recommended) if we want to have different 
      `LoKi::Hybrid::TupleTool` for each of our branches. For instance, we may 
-     want to add different information for the D*, the D0 and the soft `$ \pi $`:
+     want to add different information for the D*, the D0 and the soft $\pi$:
 
 ```python
 dstar_hybrid = dtt.Dstar.addTupleTool('LoKi::Hybrid::TupleTool/LoKi_Dstar')

first-analysis-steps/analysis-productions.md

@@ -59,7 +59,7 @@ Before making any edits, you should create a branch for your changes, and switch
 git checkout -b ${USER}/starterkit-practice
 ```
 
-Now we need to create a folder to store all the things we're going to add for our new production. For this practice production, we'll continue with the `$ B^+ \to (J/\psi \to \mu^+ \mu^-) K^+ $` decays used in the previous few lessons, so we should name the folder appropriately:
+Now we need to create a folder to store all the things we're going to add for our new production. For this practice production, we'll continue with the $B^+ \to (J/\psi \to \mu^+ \mu^-) K^+$ decays used in the previous few lessons, so we should name the folder appropriately:
 
 ```bash
 mkdir starterkit
@@ -99,7 +99,7 @@ Bu2JpsiK_24c4_MagDown:
 Here, the unindented lines are the names of jobs (although `defaults` has a special function), and the indented lines are the options we're applying to those jobs. Using this file will create one job called `Bu2JpsiK_24c4_MagDown`, that will read in data from the provided bookkeeping path. All the options applied under `defaults` are automatically applied to all other jobs - very useful for avoiding repetition. The options we're using here are copied from the Run 3 DaVinci lesson:
 
 * **application**: the version of DaVinci to use. Here we choose v64r12, see [here](http://lhcbdoc.web.cern.ch/lhcbdoc/davinci/) to check what versions are available.
-* **wg**: the working group this production is a part of. Since this is a `$ B^+ \to (J/\psi \to \mu^+ \mu^-) K^+ $` decay, we'll set this to `B2CC`.
+* **wg**: the working group this production is a part of. Since this is a $B^+ \to (J/\psi \to \mu^+ \mu^-) K^+$ decay, we'll set this to `B2CC`.
 * **inform**: optionally, you can enter your email address to receive updates on the status of your jobs.
 * **options**: the settings to use when running DaVinci. These are copied from the Run 3 DaVinci lesson.
 * **output**: the name of the output `.root` ntuples. These will get registered in bookkeeping as well.

first-analysis-steps/analysisflow.md

@@ -20,7 +20,7 @@ This is done using the software package called DaVinci.
 
 {% endcallout %}
 
-### Getting data files
+## Getting data files
 
 After preselecting data either in the Stripping, Sprucing or triggering step, users can produce ROOT files containing _ntuples_, running the DaVinci application.
 An ntuple is a (often complex) data structure typically stored within a (ROOT) file, which contains information about events or candidates in the data sample, such as the candidate mass or trigger decision flags.
@@ -39,7 +39,7 @@ We will discuss the concept of analysis preservation a bit later in this lesson.
 In first analysis steps we cover both running DaVinci on [Ganga](https://lhcb.github.io/starterkit-lessons/first-analysis-steps/davinci-grid.html) and via [Analysis Productions](https://lhcb.github.io/starterkit-lessons/first-analysis-steps/analysis-productions.html).
 
 
-### Useful high energy physics analysis tools
+## Useful high energy physics analysis tools
 
 After getting the ntuples a user usually develops new analysis code or expands an existing code, that their collaborators use. 
 Analysis code is usually based on the popular high-energy physics software tools or on the more general data analysis tools, like [numpy](https://numpy.org/) or [pandas](https://pandas.pydata.org/). 
@@ -66,7 +66,7 @@ This list is by no means exhaustive, so if there are any other tools you use oft
 
 Discussions on the new analysis tools that might be useful for the LHCb community are held in the [Work Package 4](https://lhcb-dpa.web.cern.ch/lhcb-dpa/wp4/index.html) of the Data Processing & Analysis project (DPA). 
 
-### Analysis Preservation
+## Analysis Preservation
 
 When the samples are ready one can proceed with developing the necessary macros and scripts to perform the analysis steps, such as applying additional selections, fitting distributions, computing efficiencies and acceptances, etc. 
 Starting from the ntuples a typical analysis will consist of the following steps: 

first-analysis-steps/bookkeeping.md

@@ -10,8 +10,8 @@ After this, a tree of various application and processing versions will
 eventually lead to the data you need.
 
 So, before we can run our first DaVinci job we need to locate some events. In 
-this tutorial we will use the decay `$ D^{* +} \to D^{0}\pi^{+} $` as an example, 
-where the `$ D^{0} $` decays to `$ K^{-} K^{+} $`.
+this tutorial we will use the decay $ D^{* +} \to D^{0}\pi^{+} $ as an example, 
+where the $D^{0}$ decays to $K^{-} K^{+}$.
 
 {% objectives "Learning Objectives" %}
 
@@ -40,8 +40,8 @@ representation of the [event
 type](https://cds.cern.ch/record/855452?ln=en).  The text is the human
 readable version of that.
 
-This sample of simulated events will only contain events where a `$ D^{* +} \to 
-D^{0}(\to K^{-}K^{+})\pi^{+} $` was generated within the LHCb acceptance, 
+This sample of simulated events will only contain events where a $D^{* +} \to 
+D^{0}(\to K^{-}K^{+})\pi^{+}$ was generated within the LHCb acceptance, 
 although the decay might not have been fully reconstructed. (Not all simulated 
 samples have the same requirements made on the signal decay.)
 
@@ -109,9 +109,9 @@ by typing this path and pressing the `Go` button.
 
 Think of a decay and try to find a Monte Carlo sample for it. You could use 
 the decay that your analysis is about, or if you don't have any ideas you 
-could look for the semileptonic decay `$ \Lambda_{b}^{0} \to 
-\Lambda_{c}^{+}\mu^{-}\bar{\nu}_{\mu} $`, where the `$ \Lambda_{c}^{+} $` decays 
-to `$ pK^{-}\pi^{+} $`.
+could look for the semileptonic decay $\Lambda_{b}^{0} \to 
+\Lambda_{c}^{+}\mu^{-}\bar{\nu}_{\mu}$, where the $\Lambda_{c}^{+}$ decays 
+to $pK^{-}\pi^{+}$.
 
 {% endchallenge %}
 

first-analysis-steps/dataflow-run3.md

@@ -11,22 +11,22 @@
 
 In Run 1 & 2 LHCb proved itself not only to be a high-precision
 heavy flavour physics experiment, but also extended the core physics programme to many different areas such as electroweak physics and fixed-target experiments. This incredible precision led to
-over 500 papers including breakthroughs such as the first discovery of `$ C\!P $`-violation in charm and the first observation of the decay `$ B_s^0\to \mu^+\mu^- $` among many others.
+over 500 papers including breakthroughs such as the first discovery of $C\!P$-violation in charm and the first observation of the decay $B_s^0\to \mu^+\mu^-$ among many others.
 
-In order to reach even higher precision the experiment aims to take `$ 50\,\mathrm{fb}^{-1} $` of
+In order to reach even higher precision the experiment aims to take $50\,\mathrm{fb}^{-1}$ of
 data in Run 3 by increasing the instantaneous luminosity by a factor of five.
 To be capable of dealing with the higher detector occupancy the experiment will be equipped with an entire new set of tracking detectors with higher granularity and improved radiation tolerance.
 
 One of the most important upgrades in Run 3 will be the removal of the LHCb L0 hardware triggers. As described in the following, this will bring significant changes in the data flow of the experiment both for online and offline processing. It also means that the front-end and readout electronics of all sub-detectors will be replaced, to be able
-to operate at the bunch crossing rate of `$ 40\,\mathrm{MHz} $`, as well as the photodetectors of the RICH1 detector. 
+to operate at the bunch crossing rate of $40\,\mathrm{MHz}$, as well as the photodetectors of the RICH1 detector. 
 
 ## Upgrade of the LHCb trigger system
 
 The trigger layout for Run 3 will look like this:
 
 !["Data processing chain for Run 3"](img/hidef_RTA_dataflow_widescreen.png)
 
-The LHCb trigger system will be fully redesigned by removing the L0 hardware trigger and moving to a fully-software based trigger. The hardware trigger has a rate limit of 1 MHz, which would be a limitation with the increase in luminosity. Such a low rate could be only achieved by having tight hardware trigger thresholds on `$ p_\mathrm{T} $` and `$ E_\mathrm{T} $` which is inefficient especially for fully hadronic decay modes. The removal of this bottleneck means that the full detector readout as well as running the HLT1 needs to be enabled at the average non-empty bunch crossing rate in LHCb of `$ 30\,\mathrm{MHz} $`, a not so trivial computing challenge!
+The LHCb trigger system will be fully redesigned by removing the L0 hardware trigger and moving to a fully-software based trigger. The hardware trigger has a rate limit of 1 MHz, which would be a limitation with the increase in luminosity. Such a low rate could be only achieved by having tight hardware trigger thresholds on $p_\mathrm{T}$ and $E_\mathrm{T}$ which is inefficient especially for fully hadronic decay modes. The removal of this bottleneck means that the full detector readout as well as running the HLT1 needs to be enabled at the average non-empty bunch crossing rate in LHCb of $30\,\mathrm{MHz}$, a not so trivial computing challenge!
 
 As we saw already at the [Run 1 and Run 2 dataflow lecture](https://lhcb.github.io/starterkit-lessons/first-analysis-steps/dataflow.html), the software trigger is implemented in two steps: the HLT1 which performs partial event reconstruction and simple trigger decisions to reduce the data rate, and HLT2, which performs the more computationally expensive full reconstruction and complete trigger selection. One of the most important tasks of building the events is track reconstruction, which is an inherently parallelizable process. For this purpose, HLT1 in Run 3 is implemented as part of the ```Allen project``` and run on GPUs.
 
@@ -38,7 +38,7 @@ Having the HLT1 run on GPUs imposes some different requirements on the code deve
 The raw data of events selected by HLT1 is passed on to the buffer system and stored there. The buffering of events enables to run the real-time alignment and calibration before events are entering HLT2. This is crucial because in this way calibration and alignment constants obtained can be used in the full event reconstruction performed in HLT2. For the determination of these constants, HLT1 selects dedicated calibration samples. 
 More information about the real-time alignment and calibration can be found in the [Upgrade Alignment TWIKI page](https://twiki.cern.ch/twiki/bin/view/LHCb/AlignmentInUpgrade).
 
-The total bandwidth that can be saved from HLT2 to tape is limited to `$ 10\,\mathrm{GB}/s $`. An important change in the HLT2 selections with respect to the Run 2 will be the increased use of the Turbo model. Wherever possible, the Turbo will be the baseline, so that in total for approximately 2/3 of data only the data of the signal candidate (raw and reconstructed) will be saved and no further offline reconstruction will be possible. This results in significantly smaller event sizes so that more events can be saved.
+The total bandwidth that can be saved from HLT2 to tape is limited to $10\,\mathrm{GB}/s$. An important change in the HLT2 selections with respect to the Run 2 will be the increased use of the Turbo model. Wherever possible, the Turbo will be the baseline, so that in total for approximately 2/3 of data only the data of the signal candidate (raw and reconstructed) will be saved and no further offline reconstruction will be possible. This results in significantly smaller event sizes so that more events can be saved.
 
 For details and tutorials on how to develop HLT2 line selections as well as how to check their efficiencies and data rates follow the [Moore documentation](https://lhcbdoc.web.cern.ch/lhcbdoc/moore/master/index.html).
 

first-analysis-steps/decay-tree-fitter.md

@@ -111,7 +111,7 @@ a vertex fit acts like a vertex constraint, improving the opening-angle resoluti
 {% endcallout %} 
 
 
-Now let us look at the refitted mass of the `$ D^{*+} $`, with the `$ D^0 $` constrained to its nominal mass.
+Now let us look at the refitted mass of the $D^{*+}$, with the $D^0$ constrained to its nominal mass.
 It is stored in the variable `Dstar_ConsD_M`.
 If you plot this you will note that some values are unphysical.
 So, let's restrict the range we look at to something that makes sense.

first-analysis-steps/interactive-dst.md

@@ -176,9 +176,9 @@ one with:
 >>> print(candidates[0])
 ```
 
-Which will print out some information about the [Particle](https://lhcb-doxygen.web.cern.ch/lhcb-doxygen/davinci/latest/d0/d13/class_l_h_cb_1_1_particle.html). In our case a `$ D^{* +} $` ([particle ID number](http://pdg.lbl.gov/2019/reviews/rpp2018-rev-monte-carlo-numbering.pdf) 413). You can access its decay products with
+Which will print out some information about the [Particle](https://lhcb-doxygen.web.cern.ch/lhcb-doxygen/davinci/latest/d0/d13/class_l_h_cb_1_1_particle.html). In our case a $D^{* +}$ ([particle ID number](http://pdg.lbl.gov/2019/reviews/rpp2018-rev-monte-carlo-numbering.pdf) 413). You can access its decay products with
 `candidates[0].daughtersVector()[0]` and `candidates[0].daughtersVector()[1]`,
-which will be a `$ D^{0} $` and a `$ \pi^{+} $`.
+which will be a $D^{0}$ and a $\pi^{+}$.
 
 There is a useful tool for printing out decay trees, which you can
 pass the top level particle to and it will print out the full decay tree etc:

first-analysis-steps/loki-functors.md

@@ -66,7 +66,7 @@ candidate = candidates[0]
 
 The object `candidate `, loaded from the DST, is of type `LHCb::Particle` and we are looking at its representation via python bindings. 
 We can do `help(candidate)` to find out which functions are available.
-We can try to get very simple properties of the `$ D^{* +} $` candidate. Let's start from the components of its momentum.
+We can try to get very simple properties of the $D^{* +}$ candidate. Let's start from the components of its momentum.
 This can be done calling the function `momentum()` for our candidate in the following way:
 ```python
 p_x = candidate.momentum().X()
@@ -134,8 +134,8 @@ print (PT(candidate)/GeV)
 
 {% endcallout %} 
 
-If we want to get the properties of the `$ D^{* +} $` vertex, for example its fit 
-quality (`$ \chi^2 $`), we need to pass a vertex object to the vertex functor.
+If we want to get the properties of the $D^{* +}$ vertex, for example its fit 
+quality ($\chi^2$), we need to pass a vertex object to the vertex functor.
 
 ```python
 from LoKiPhys.decorators import VCHI2
@@ -219,11 +219,11 @@ The list can be overwhelming, so it's also worth checking a more curated selecti
 {% endcallout %} 
 
 So far we've only looked at the properties of the head of the decay (that is, 
-the `$ D^{* +} $`), but what if we want to get information about its decay products? As 
+the $D^{* +}$), but what if we want to get information about its decay products? As 
 an example, let's get the largest transverse momentum of the final state 
 particles.
 A simple solution would be to navigate the tree and calculate the maximum 
-`$ p_{\text{T}} $`.
+$p_{\text{T}}$.
 
 ```python
 def find_tracks(particle):
@@ -311,7 +311,7 @@ Out[10]:
 
 ```
 we know that `D0` is the first child and `pi+` is the second.
-Therefore, to access the mass of the `$ D^{0} $` we have 2 options:
+Therefore, to access the mass of the $D^{0}$ we have 2 options:
 ```python
 from LoKiPhys.decorators import CHILD
 # Option 1
@@ -328,7 +328,7 @@ Evaluate the quality of the D0 decay vertex.
 
 {% endchallenge %} 
 
-In the similar way, we may access properties of child of the child: for example, a kaon from the `$ D^{0} $` decay:
+In the similar way, we may access properties of child of the child: for example, a kaon from the $D^{0}$ decay:
 ```python
 from LoKiPhys.decorators import CHILD
 mass_kaon = CHILD(CHILD(M, 1),1)(candidate)