1- # Configuration file for the Sphinx documentation builder.
2- #
3- # This file only contains a selection of the most common options. For a full
4- # list see the documentation:
5- # https://www.sphinx-doc.org/en/master/usage/configuration.html
6-
7- # -- Path setup --------------------------------------------------------------
8-
9- # If extensions (or modules to document with autodoc) are in another directory,
10- # add these directories to sys.path here. If the directory is relative to the
11- # documentation root, use os.path.abspath to make it absolute, like shown here.
12-
13- import pathlib
141import os
2+ import pathlib
153import shutil
164import sys
175import warnings
6+ from functools import partial
187
8+ # -- Filter Warnings -----------------------------------------------------------
199# ignore numpy warnings, see:
2010# https://stackoverflow.com/questions/40845304/runtimewarning-numpy-dtype-size-changed-may-indicate-binary-incompatibility
2111warnings .filterwarnings ("ignore" , message = "numpy.dtype size changed" )
2515warnings .filterwarnings (
2616 "ignore" ,
2717 category = UserWarning ,
28- message = "Matplotlib is currently using agg, which is a" " non-GUI backend, so cannot show the figure."
18+ message = "Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure." ,
2919)
3020
21+ # suppress Sphinx cache-related warnings
22+ suppress_warnings = ["config.cache" ]
23+
24+ # -- Path setup ---------------------------------------------------------------
25+
26+ # If extensions (or modules to document with autodoc) are in another directory,
27+ # add these directories to sys.path here. If the directory is relative to the
28+ # documentation root, use os.path.abspath to make it absolute, like shown here.
3129
3230TOPLEVEL_DIR = pathlib .Path (__file__ ).parent .parent .absolute ()
3331ABOUT_FILE = TOPLEVEL_DIR / "__init__.py"
3937with ABOUT_FILE .open ("r" ) as f :
4038 exec (f .read (), ABOUT_accelerator_timeline )
4139
40+
41+ # -- Accelerator Timeline specific setup ---------------------------------------
4242# Set environment variable for scripts to check if we are in sphinx-mode
43- from utilities .sphinx_helper import SPHINX_BUILD_ENVIRON
44- os .environ [SPHINX_BUILD_ENVIRON ] = '1'
43+ from utilities .sphinx_helper import SPHINX_BUILD_ENVIRON # noqa: E402
4544
45+ os .environ [SPHINX_BUILD_ENVIRON ] = '1'
4646
4747# Copy accelerator data file
4848shutil .copy2 (
49- TOPLEVEL_DIR / "accelerator-parameters.csv" ,
49+ TOPLEVEL_DIR / "accelerator-parameters.csv" ,
5050 TOPLEVEL_DIR / "doc" / "accelerator-parameters.csv"
5151)
5252
6969
7070# General information about the project.
7171project = ABOUT_accelerator_timeline ["__title__" ]
72- copyright_ = '2019-2023 , pyLHC/OMC-TEAM'
72+ copyright_ = '2019-2025 , pyLHC/OMC-TEAM'
7373author = ABOUT_accelerator_timeline ["__author__" ]
7474
7575rst_prolog = f"""
113113# List of patterns, relative to source directory, that match files and
114114# directories to ignore when looking for source files.
115115# This patterns also effect to html_static_path and html_extra_path
116- exclude_patterns = ["_build" , "Thumbs.db" , ".DS_Store" , "docs" , "docker" , "tests" , ".github" , ".vscode" ]
116+ exclude_patterns = ["_build" , "Thumbs.db" , ".DS_Store" , "docs" , "docker" , "tests" , ".github" , ".vscode" , ".venv" ]
117117
118118# The reST default role (used for this markup: `text`) to use for all
119119# documents.
189189# bibtex_reference_style = "label"
190190
191191# -- Setup scrapers for the gallery ------------------------------------------
192- from plotly .io ._sg_scraper import plotly_sg_scraper
193- import plotly .io as pio
192+ import plotly .io as pio # noqa: E402
193+ from plotly .io ._sg_scraper import plotly_sg_scraper # noqa: E402
194+
194195pio .renderers .default = 'sphinx_gallery'
195196
196197# To use SVG outputs when scraping matplotlib figures for the sphinx-gallery
197- from sphinx_gallery .scrapers import matplotlib_scraper
198- from sphinx_gallery .sorting import ExampleTitleSortKey
199- class matplotlib_svg_scraper (object ):
200- def __repr__ (self ):
201- return self .__class__ .__name__
202-
203- def __call__ (self , * args , ** kwargs ):
204- return matplotlib_scraper (* args , format = "svg" , ** kwargs )
198+ from sphinx_gallery .scrapers import matplotlib_scraper # noqa: E402
199+ from sphinx_gallery .sorting import ExampleTitleSortKey # noqa: E402
205200
206201# Config for the matplotlib plot directive
207202plot_formats = [("svg" , 250 )]
208203
209204# image_scrapers = (matplotlib_svg_scraper(), plotly_sg_scraper,)
210- image_scrapers = (matplotlib_svg_scraper (), )
205+ image_scrapers = (partial ( matplotlib_scraper , format = "svg" ), plotly_sg_scraper )
211206
212207# -- Configuration for the sphinx-gallery extension -------------------------------
208+
213209sphinx_gallery_conf = {
214- "examples_dirs" : ["../" ], # directory where to find plotting scripts
210+ "examples_dirs" : [TOPLEVEL_DIR ], # directory where to find plotting scripts
215211 "gallery_dirs" : ["gallery" ], # directory where to store generated plots
216212 "filename_pattern" : "^((?!sgskip).)*$" , # which files to execute
217- "subsection_order" : ExampleTitleSortKey ,
218- "within_subsection_order" : ExampleTitleSortKey ,
213+ "subsection_order" : ExampleTitleSortKey ( TOPLEVEL_DIR ) ,
214+ "within_subsection_order" : ExampleTitleSortKey ( TOPLEVEL_DIR ) ,
219215 "reference_url" : {"accelerator_timeline" : None }, # Sets up intersphinx in gallery code
220216 "backreferences_dir" : "gen_modules/backreferences" , # where function/class granular galleries are stored
221217 # Modules for which function/class level galleries are created
@@ -228,6 +224,7 @@ def __call__(self, *args, **kwargs):
228224 "compress_images" : ("images" , "thumbnails" , "-o1" ),
229225 "only_warn_on_example_error" : True , # keep the build going if an example fails, very important for doc workflow
230226 "download_all_examples" : False ,
227+ "ignore_pattern" : r"^(tst_|_|\.).*" , # ignore test/private files
231228}
232229
233230# Config for the sphinx_panels extension
@@ -247,8 +244,8 @@ def __call__(self, *args, **kwargs):
247244# documentation.
248245html_theme_options = {
249246 "collapse_navigation" : False ,
250- "display_version" : True ,
251247 "logo_only" : True ,
248+ "version_selector" : True ,
252249 "navigation_depth" : 2 ,
253250}
254251
@@ -547,7 +544,7 @@ def __call__(self, *args, **kwargs):
547544# -- Autodoc Configuration ---------------------------------------------------
548545
549546# Add here all modules to be mocked up. When the dependencies are not met
550- # at building time.
547+ # at building time.
551548autodoc_mock_imports = []
552549
553550# -- Instersphinx Configuration ----------------------------------------------
0 commit comments