fix: minor changes to docs (#125)

ekauffma · web-flow · commit 5bcbe66683c9 · 2023-04-20T13:46:22.000+02:00
* changed tab titles on docs
* changed funcx+pyhf typo
* added ipython to docs/requirements for python syntax highlighting
* rearranged to avoid warnings and fixed edit links
* added docs badge in readme
* added requirements.txt for event plotting notebook and got rid of unnecessary utils (removed tree printing)
* added other documentation link in readme
diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # Analysis Grand Challenge (AGC)
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7274936.svg)](https://doi.org/10.5281/zenodo.7274936)
+[![Documentation Status](https://readthedocs.org/projects/agc/badge/?version=latest)](https://agc.readthedocs.io/en/latest/?badge=latest)
+
 
 The Analysis Grand Challenge (AGC) is about performing the last steps in an analysis pipeline at scale to test workflows envisioned for the HL-LHC.
 This includes
@@ -29,7 +31,7 @@ Additional information is available in two workshops focused on the AGC:
 - [IRIS-HEP AGC Tools 2021 Workshop, Nov 3–4 2021](https://indico.cern.ch/e/agc-tools-workshop)
 - [IRIS-HEP AGC Tools 2022 Workshop, April 25–26 2022](https://indico.cern.ch/e/agc-tools-2)
 
-We also have a [dedicated webpage](https://iris-hep.org/grand-challenges.html).
+We also have a [dedicated webpage](https://iris-hep.org/grand-challenges.html) and a [website for documentation](https://agc.readthedocs.io/en/latest/?badge=latest).
 
 ## AGC and IRIS-HEP
 
diff --git a/docs/cms-open-data-ttbar b/docs/cms-open-data-ttbar
@@ -1 +1 @@
-../analyses/cms-open-data-ttbar/
+../analyses/cms-open-data-ttbar
diff --git a/docs/conf.py b/docs/conf.py
@@ -38,6 +38,9 @@
     "**.ipynb_checkpoints",
     ".DS_Store",
     ".env",
+    "atlas-open-data-hzz/alternative_implementations/*",
+    "cms-open-data-ttbar/coffea.ipynb",
+    "*/README.md",
 ]
 
 # -- Options for HTML output -------------------------------------------------
@@ -54,9 +57,10 @@
 html_theme_options = {
     "home_page_in_toc": True,
     "repository_url": "https://github.com/iris-hep/analysis-grand-challenge",
+    "repository_branch": "main/docs",
     "use_repository_button": True,
     "use_issues_button": True,
-    "use_edit_page_button": True,
+    "use_edit_page_button": False,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
diff --git a/docs/event-plotting/plotEvents.ipynb b/docs/event-plotting/plotEvents.ipynb
diff --git a/docs/event-plotting/plotEvents.py b/docs/event-plotting/plotEvents.py
@@ -15,7 +15,6 @@
 
 # %% [markdown]
 # # Plot $t\bar{t}$ Events
-# ______
 #
 # This notebook allows one to visualize events, including jets and the genParticles they are matched to. Trees from events are also printed using the `printTrees` method in `utils`.
 
@@ -27,7 +26,6 @@
 import matplotlib.pyplot as plt
 import awkward as ak
 import particle
-from utils import printTrees
 from matplotlib.patches import Patch
 from matplotlib.lines import Line2D
 
@@ -167,14 +165,6 @@
 # %% tags=[]
 for iEvt in range(10):
     
-    print("-----------------------------------------------------------------------------------------------")
-    print("-----------------------------------------------------------------------------------------------")
-    print(f"                                         EVENT {iEvt}                                         ")
-    print("-----------------------------------------------------------------------------------------------")
-    # print event tree from genParticles
-    printTrees(selected_genpart_region[iEvt])
-    print("-----------------------------------------------------------------------------------------------")
-    
     # define mpl figure
     fig,axs = plt.subplots(1,2,figsize=(10,6),gridspec_kw={'width_ratios': [2.3, 1]})
     
diff --git a/docs/event-plotting/requirements.txt b/docs/event-plotting/requirements.txt
@@ -0,0 +1,6 @@
+awkward==1.10.3
+coffea==0.7.21
+matplotlib==3.7.1
+numpy==1.23.5
+particle==0.21.0
+uproot==4.1.6
diff --git a/docs/event-plotting/utils.py b/docs/event-plotting/utils.py
diff --git a/docs/index.rst b/docs/index.rst
@@ -67,8 +67,8 @@ More details: what is being investigated in the AGC context
 * **New user interfaces**: Complementary services that present the analyst with a notebook-based interface.  Example software: Jupyter.
 * **Data access**: Services that provide quick access to the experiment’s official data sets, often allowing simple derivations and local caching for efficient access.  Example software and services: ``Rucio``, ``ServiceX``, ``SkyHook``, ``iDDS``, ``RNTuple``.
 * **Event selection**: Systems/frameworks allowing analysts to process entire datasets, select desired events, and calculate derived quantities.  Example software and services: ``coffea``, ``awkward-array``, ``func_adl``, ``RDataFrame``.
-Histogramming and summary statistics: Closely tied to the event selection, histogramming tools provide physicists with the ability to summarize the observed quantities in a dataset.  Example software and services: ``coffea``, ``func_adl``, ``cabinetry``, ``hist``.
-* **Statistical model building and fitting**: Tools that translate specifications for event selection, summary statistics, and histogramming quantities into statistical models, leveraging the capabilities above, and perform fits and statistical analysis with the resulting models.  Example software and services: ``cabinetry``, ``pyhf``, ``FuncX``+``pyhf`` fitting service
+* **Histogramming and summary statistics**: Closely tied to the event selection, histogramming tools provide physicists with the ability to summarize the observed quantities in a dataset.  Example software and services: ``coffea``, ``func_adl``, ``cabinetry``, ``hist``.
+* **Statistical model building and fitting**: Tools that translate specifications for event selection, summary statistics, and histogramming quantities into statistical models, leveraging the capabilities above, and perform fits and statistical analysis with the resulting models.  Example software and services: ``cabinetry``, ``pyhf``, ``FuncX`` + ``pyhf`` fitting service
 * **Reinterpretation / analysis preservation**:  Standards for capturing the entire analysis workflow, and services to reuse the workflow which enables reinterpretation.  Example software and services: ``REANA``, ``RECAST``.
 
 Acknowledgements
@@ -79,7 +79,7 @@ This work was supported by the U.S. National Science Foundation (NSF) cooperativ
 .. toctree::
    :maxdepth: 2
    :titlesonly:
-   :caption: CMS AGC
+   :caption: ttbar with CMS Open Data
    :glob:
 
    cms-open-data-ttbar/ttbar_analysis_pipeline
@@ -90,7 +90,7 @@ This work was supported by the U.S. National Science Foundation (NSF) cooperativ
 .. toctree::
    :maxdepth: 2
    :titlesonly:
-   :caption: ATLAS AGC
+   :caption: H>ZZ* with ATLAS Open Data
    :glob:
 
    atlas-open-data-hzz/HZZ_analysis_pipeline
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,4 @@
+ipython>=8.12.0
 myst_parser>=1.0.0
 nbsphinx>=0.9.1
 pydata-sphinx-theme==0.13.1
diff --git a/docs/taskbackground.rst b/docs/taskbackground.rst
@@ -19,7 +19,9 @@ To look at more events, take a look at **Plot :math:`t\bar{t}` Events**.
   :width: 80%
   :alt: Example of a :math:`t\bar{t}` event in our signal region.
   
-The tree of the above event looks something like::
+The tree of the above event looks something like
+
+.. code-block:: text
 
     g
     ├── t

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-../analyses/cms-open-data-ttbar/`
	`1`	`+../analyses/cms-open-data-ttbar`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+ipython>=8.12.0`
`1`	`2`	`myst_parser>=1.0.0`
`2`	`3`	`nbsphinx>=0.9.1`
`3`	`4`	`pydata-sphinx-theme==0.13.1`
Original file line number	Diff line number	Diff line change
@@ -19,7 +19,9 @@ To look at more events, take a look at Plot :math:`t\bar{t}` Events.
`19`	`19`	`:width: 80%`
`20`	`20`	:alt: Example of a :math:`t\bar{t}` event in our signal region.
`21`	`21`
`22`		`-The tree of the above event looks something like::`
	`22`	`+The tree of the above event looks something like`
	`23`	`+`
	`24`	`+.. code-block:: text`
`23`	`25`
`24`	`26`	`g`
`25`	`27`	`├── t`