Update Readme with note for developers

.github/workflows/documentation.yml

@@ -1,10 +1,8 @@
 # Build documentation
+# The build is uploaded as artifact if the triggering event is a push for a pull request
+# The build is published to github pages if the triggering event is a push to the master branch (PR merge)
 name: Build and upload documentation
 
-defaults:
-  run:
-    shell: bash
-
 on:  # Runs on any push event in a PR or any push event to master
   pull_request:
   push:
@@ -13,48 +11,4 @@ on:  # Runs on any push event in a PR or any push event to master
 
 jobs:
   documentation:
-    name: ${{ matrix.os }} / ${{ matrix.python-version }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:  # only lowest supported python on ubuntu-latest
-        os: [ubuntu-latest]
-        python-version: [3.9]
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Install LaTeX
-        run: sudo apt-get install -y texlive-latex-base # texlive-fonts-extra texlive-fonts-recommended texlive-latex-extra texlive-latex-recommended ghostscript
-
-      - name: Install optipng
-        run: sudo apt-get install -y optipng
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Upgrade pip
-        run: python -m pip install --upgrade pip
-
-      - name: Install dependencies
-        run: python -m pip install -r doc/requirements.txt
-
-      - name: Build documentation
-        run: python -m sphinx -v -b html doc doc_build -d doc_build
-
-      - name: Upload build artifacts  # upload artifacts so reviewers can have a quick look without building documentation from the branch locally
-        if: success() && github.event_name == 'pull_request'  # only for pushes in PR
-        uses: actions/upload-artifact@v3
-        with:
-          name: site-build
-          path: doc_build
-          retention-days: 5 
-
-      - name: Upload documentation to gh-pages
-        if: success() && github.ref == 'refs/heads/master'  # only for pushes to master
-        uses: JamesIves/github-pages-deploy-action@v4
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          branch: gh-pages
-          folder: doc_build
+        uses: pylhc/.github/.github/workflows/documentation.yml@master

README.md

@@ -4,40 +4,44 @@
 [![GitHub release](https://img.shields.io/github/release/pylhc/accelerator_timeline.svg?style=popout)](https://github.com/pylhc/accelerator_timeline/)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8316137.svg)](https://doi.org/10.5281/zenodo.8316137)
 
-In this package, the main parameters of major historical, modern and possible future accelerators are 
+In this package, the main parameters of major historical, modern and possible future accelerators are
 collected, including references to the origin of the collected data, into a single csv:
 
- -  [accelerator-parameters.csv](accelerator-parameters.csv).
+- [accelerator-parameters.csv](accelerator-parameters.csv).
 
-
-
-## Installation 
+## Installation
 
 This package is mostly for collecting and sharing the data of the accelerators within
-the CSV file. 
+the CSV file.
 
-
-To get the data, either download the [accelerator-parameters.csv](accelerator-parameters.csv) directly, 
+To get the data, either download the [accelerator-parameters.csv](accelerator-parameters.csv) directly,
 or clone the repository via `git`, e.g.::
 
-```
+```bash
 git clone https://github.com/pylhc/accelerator_timeline.git
 ```
 
 ## Example Scripts
 
 In addition, small python scripts are provided to explore the data via and create Livingston-like plots.
 These charts are available interactively at:
- 
- - [pylhc.github.io/accelerator_timeline](https://pylhc.github.io/accelerator_timeline).
+
+- [pylhc.github.io/accelerator_timeline](https://pylhc.github.io/accelerator_timeline).
 
 The python code itself can be found at
 
- - [interactive_charts.py](interactive_charts.py), creating the interactive charts via plotly.
- - [export_charts.py](export_charts.py), making publication-grade exports to pdf via matplotlib.
+- [interactive_charts.py](interactive_charts.py), creating the interactive charts via plotly.
+- [export_charts.py](export_charts.py), making publication-grade exports to pdf via matplotlib.
 
 The requirements for the scripts can be found in the respective `requirements_*.txt` file.
 
 ![Center of Mass](images/energy.png)
 ![Luminosity](images/luminosity.png)
 ![LuminosityVsEnergy](images/luminosity-vs-energy.png)
+
+## Note for Developers
+
+Updating the data in the CSV will automatically update the charts in the
+[pylhc.github.io/accelerator_timeline](https://pylhc.github.io/accelerator_timeline) website via GitHub Actions.
+The pictures in the `images/` folder (which are also linked in this `README`) are **not** automatically generated
+and need to be updated manually by running the `export_charts.py` script and committing the changes.

accelerator-parameters.csv

@@ -43,8 +43,8 @@ FCC-ee WW,CERN,Switzerland,2043*,,e+e-,80,,2.8E+035,97750,https://journals.aps.o
 FCC-ee ZH,CERN,Switzerland,2045*,,e+e-,120,,8.5E+034,97750,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006 https://doi-org.ezproxy.cern.ch/10.1140/epjst/e2019-900045-4
 FCC-ee ttbar,CERN,Switzerland,2049*,,e+e-,182.5,,1.55E+034,97750,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006 https://doi-org.ezproxy.cern.ch/10.1140/epjst/e2019-900045-4
 FCC-hh,CERN,Switzerland,2070*,,p+p+,50000,,3E+035,97750,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006
-CEPC,IHEP,China,2035*,,e+e-,45.5,,3.2E+035,100000,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006 https://arxiv.org/abs/1809.00285 https://www.researchgate.net/publication/359254433_Snowmass_2021_White_Paper_AF4_-_SPPC
-SppC,IHEP,China,2050*,,p+p+,37500,,1E+035,100000,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006 https://www.researchgate.net/publication/359254433_Snowmass_2021_White_Paper_AF4_-_SPPC
+CEPC,IHEP,China,2035*,,e+e-,45.5,,3.2E+035,100000,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006 https://arxiv.org/abs/1809.00285 https://doi.org/10.48550/arXiv.2203.07987
+SppC,IHEP,China,2050*,,p+p+,37500,,1E+035,100000,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006 https://doi.org/10.48550/arXiv.2203.07987
 ILC v1,Fermilab,USA,2035*,,e+e-,125,,1.35E+034,20500,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006 https://arxiv.org/pdf/1901.09829.pdf
 ILC v2,Fermilab,USA,2040*,,e+e-,250,,1.8E+034,31000,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006 https://arxiv.org/pdf/1901.09829.pdf
 ILC v3,Fermilab,USA,2045*,,e+e-,500,,4.9E+034,40000,https://journals.aps.org/rmp/pdf/10.1103/RevModPhys.93.015006 https://arxiv.org/pdf/1901.09829.pdf

doc/Makefile

@@ -51,11 +51,6 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-josch:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ../../Documentation/accelerator_timeline-doc
-	@echo
-	@echo "Build finished. The HTML pages are in ../../Documentation/accelerator_timeline-doc."
-
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

doc/_static/css/custom.css

@@ -1,13 +1,13 @@
 :root {
-  --nav-side-width: 300px;  /* default is 300px */
+  --nav-side-width: 250px;  /* default is 300px */
   /* for 100% width */
   /*--nav-content-width: 100%;*/
   /*--local-toc-width: 300px;*/
   /*--nav-content-width-wide: calc(100% - var(--local-toc-width)); /* 100% here is fullscreen */
   /*--local-toc-left: calc(100% - var(--local-toc-width)); /* 100% here is w/o sidebar */
 
   /* for fixed widths */
-  --nav-content-width: 800px;  /* default is 800px */
+  --nav-content-width: 1000px;  /* default is 800px */
   --nav-content-width-wide: var(--nav-content-width);
   --local-toc-width: calc(100% - var(--nav-content-width-wide));
   --local-toc-left: calc(var(--nav-content-width-wide) + var(--nav-side-width));
@@ -57,7 +57,7 @@
   border: none;
 }
 
-/* Hide the first two entries (combined in the first <ul>) of the nav-bar, 
+/* Hide the first two entries (combined in the first <ul>) of the nav-bar,
     as they are coming from the included gallery */
 
 .wy-menu-vertical ul:nth-child(-n + 1) {
@@ -198,7 +198,7 @@ em.sig-param span.default_value {
 
 
 /* Format Tables
-   Not sure why the following were in the css, 
+   Not sure why the following were in the css,
    but some of them break the csv table formatting.
    I left those in, that looked good.
 */

doc/conf.py

@@ -1,21 +1,11 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
-import pathlib
 import os
+import pathlib
 import shutil
 import sys
 import warnings
+from functools import partial
 
+# -- Filter Warnings -----------------------------------------------------------
 # ignore numpy warnings, see:
 # https://stackoverflow.com/questions/40845304/runtimewarning-numpy-dtype-size-changed-may-indicate-binary-incompatibility
 warnings.filterwarnings("ignore", message="numpy.dtype size changed")
@@ -25,9 +15,17 @@
 warnings.filterwarnings(
     "ignore",
     category=UserWarning,
-    message="Matplotlib is currently using agg, which is a" " non-GUI backend, so cannot show the figure.",
+    message="Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.",
 )
 
+# suppress Sphinx cache-related warnings
+suppress_warnings = ["config.cache"]
+
+# -- Path setup ---------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
 
 TOPLEVEL_DIR = pathlib.Path(__file__).parent.parent.absolute()
 ABOUT_FILE = TOPLEVEL_DIR / "__init__.py"
@@ -39,14 +37,16 @@
 with ABOUT_FILE.open("r") as f:
     exec(f.read(), ABOUT_accelerator_timeline)
 
+
+# -- Accelerator Timeline specific setup ---------------------------------------
 # Set environment variable for scripts to check if we are in sphinx-mode
-from utilities.sphinx_helper import SPHINX_BUILD_ENVIRON
-os.environ[SPHINX_BUILD_ENVIRON] = '1'
+from utilities.sphinx_helper import SPHINX_BUILD_ENVIRON  # noqa: E402
 
+os.environ[SPHINX_BUILD_ENVIRON] = '1'
 
 # Copy accelerator data file
 shutil.copy2(
-    TOPLEVEL_DIR / "accelerator-parameters.csv", 
+    TOPLEVEL_DIR / "accelerator-parameters.csv",
     TOPLEVEL_DIR / "doc" / "accelerator-parameters.csv"
 )
 
@@ -69,7 +69,7 @@
 
 # General information about the project.
 project = ABOUT_accelerator_timeline["__title__"]
-copyright_ = '2019-2023, pyLHC/OMC-TEAM'
+copyright_ = '2019-2025, pyLHC/OMC-TEAM'
 author = ABOUT_accelerator_timeline["__author__"]
 
 rst_prolog = f"""
@@ -113,7 +113,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "docs", "docker", "tests", ".github", ".vscode"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "docs", "docker", "tests", ".github", ".vscode", ".venv"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -189,33 +189,29 @@
 # bibtex_reference_style = "label"
 
 # -- Setup scrapers for the gallery ------------------------------------------
-from plotly.io._sg_scraper import plotly_sg_scraper
-import plotly.io as pio
+import plotly.io as pio  # noqa: E402
+from plotly.io._sg_scraper import plotly_sg_scraper  # noqa: E402
+
 pio.renderers.default = 'sphinx_gallery'
 
 # To use SVG outputs when scraping matplotlib figures for the sphinx-gallery
-from sphinx_gallery.scrapers import matplotlib_scraper
-from sphinx_gallery.sorting import ExampleTitleSortKey
-class matplotlib_svg_scraper(object):
-    def __repr__(self):
-        return self.__class__.__name__
-
-    def __call__(self, *args, **kwargs):
-        return matplotlib_scraper(*args, format="svg", **kwargs)
+from sphinx_gallery.scrapers import matplotlib_scraper  # noqa: E402
+from sphinx_gallery.sorting import ExampleTitleSortKey  # noqa: E402
 
 # Config for the matplotlib plot directive
 plot_formats = [("svg", 250)]
 
 # image_scrapers = (matplotlib_svg_scraper(), plotly_sg_scraper,)
-image_scrapers = (matplotlib_svg_scraper(),)
+image_scrapers = (partial(matplotlib_scraper, format="svg"), plotly_sg_scraper)
 
 # -- Configuration for the sphinx-gallery extension -------------------------------
+
 sphinx_gallery_conf = {
-    "examples_dirs": ["../"],  # directory where to find plotting scripts
+    "examples_dirs": [TOPLEVEL_DIR],  # directory where to find plotting scripts
     "gallery_dirs": ["gallery"],  # directory where to store generated plots
     "filename_pattern": "^((?!sgskip).)*$",  # which files to execute
-    "subsection_order": ExampleTitleSortKey,
-    "within_subsection_order": ExampleTitleSortKey,
+    "subsection_order": ExampleTitleSortKey(TOPLEVEL_DIR),
+    "within_subsection_order": ExampleTitleSortKey(TOPLEVEL_DIR),
     "reference_url": {"accelerator_timeline": None},  # Sets up intersphinx in gallery code
     "backreferences_dir": "gen_modules/backreferences",  # where function/class granular galleries are stored
     # Modules for which function/class level galleries are created
@@ -228,6 +224,7 @@ def __call__(self, *args, **kwargs):
     "compress_images": ("images", "thumbnails", "-o1"),
     "only_warn_on_example_error": True,  # keep the build going if an example fails, very important for doc workflow
     "download_all_examples": False,
+    "ignore_pattern": r"^(tst_|_|\.).*",  # ignore test/private files
 }
 
 # Config for the sphinx_panels extension
@@ -247,8 +244,8 @@ def __call__(self, *args, **kwargs):
 # documentation.
 html_theme_options = {
     "collapse_navigation": False,
-    "display_version": True,
     "logo_only": True,
+    "version_selector": True,
     "navigation_depth": 2,
 }
 
@@ -547,7 +544,7 @@ def __call__(self, *args, **kwargs):
 # -- Autodoc Configuration ---------------------------------------------------
 
 # Add here all modules to be mocked up. When the dependencies are not met
-# at building time. 
+# at building time.
 autodoc_mock_imports = []
 
 # -- Instersphinx Configuration ----------------------------------------------