20sys.path.insert(0, os.path.abspath(
"extensions"))
36 'sphinx.ext.intersphinx',
40 'sphinx.ext.napoleon',
41 'sphinx.ext.viewcode',
42 'sphinx.ext.autosectionlabel',
43 'sphinx_codeautolink',
47 'sphinxcontrib.programoutput',
48 'IPython.sphinxext.ipython_console_highlighting',
53codeautolink_warn_on_missing_inventory =
False
54codeautolink_warn_on_failed_resolve =
False
56basf2_doxygen_xml_dir = f
"{os.environ.get('BELLE2_RELEASE_DIR', os.environ.get('BELLE2_LOCAL_DIR'))}/build/doxygen/xml"
58nbsphinx_allow_errors =
True
64autosectionlabel_prefix_document =
True
65suppress_warnings = [
'autosectionlabel.*',
'codeautolink.*']
68templates_path = [
'_sphinxtemplates']
83copyright =
'Belle II Collaboration'
84author =
'Belle II Software Group'
91version = subprocess.check_output([
"git",
"rev-parse",
"--short",
"HEAD"]).decode().strip()
93basf2_repository =
"https://gitlab.desy.de/belle2/software/basf2/"
94basf2_commitid = subprocess.check_output([
"git",
"rev-parse",
"HEAD"]).decode().strip()
95basf2_issues =
"https://gitlab.desy.de/belle2/software/basf2/-/issues/"
98release = os.environ.get(
'BELLE2_RELEASE',
'development')
100 release =
'development'
103keep_warnings = release ==
"development"
104nitpicky = keep_warnings
108for entry
in [
'cppyy.gbl.TObject',
'cppyy.gbl.TFile',
'ROOT.TFile']:
109 nitpick_ignore.append((
'py:class', entry))
110for entry
in [
'int',
'bool',
'list',
'str',
'object',
'None',
'LogConfig',
'ProcessStatistics.ModuleStatistics']:
111 nitpick_ignore.append((
'py:class', entry +
' :'))
113basf2_doxygen_baseurl = f
"https://software.belle2.org/{release}/doxygen/"
131exclude_patterns = [
'.*',
'_sphinxbuild',
'Thumbs.db',
'build',
'include',
'lib',
'bin',
'modules',
'data',
'site_scons']
134 light_packages = {entry.strip(
'/')
for entry
in open(
'../../.light').read().split()
if entry.endswith(
'/')}
135 for entry
in os.listdir(
"../../"):
136 if entry.find(
'.') > -1
or os.path.isfile(entry)
or entry
in exclude_patterns
or entry
in light_packages:
138 exclude_patterns.append(entry)
143exclude_patterns.remove(
"build")
144exclude_patterns += [
'build/html',
'build/latex',
'build/json',
'build/Linux*',
'build/belle2_tools']
146exclude_patterns += [
'**/*.ipynb',
'*.ipynb']
164pygments_style =
'sphinx'
173todo_include_todos =
False
184html_theme =
'sphinx_book_theme'
192html_theme_path = [
"_themes", ]
203html_logo =
"b2logo.svg"
213html_static_path = [
'_sphinxstatic']
278htmlhelp_basename =
'basf2doc'
284 'papersize':
'a4paper',
290 'preamble':
'\\setcounter{tocdepth}{2}',
300 (master_doc,
'basf2.tex',
'Belle II Software Documentation',
306latex_logo =
"belle2-logo.pdf"
310latex_use_parts =
True
311latex_show_urls =
'footnote'
312latex_show_pagerefs =
True
332 (master_doc,
'basf2',
'basf2 Documentation',
346 (master_doc,
'basf2',
'basf2 Documentation',
347 author,
'basf2',
'One line description of project.',
364intersphinx_mapping = {
'python': (
'https://docs.python.org/3.11/',
None),
365 'numpy': (
'https://numpy.org/doc/stable/',
None),
366 'scipy': (
'https://docs.scipy.org/doc/scipy/',
None),
367 'pandas': (
'https://pandas.pydata.org/docs/',
None),
368 'matplotlib': (
'https://matplotlib.org/stable/',
None),
369 'b2luigi': (
'https://b2luigi.belle2.org/',
None),
370 'gbasf2': (
'https://gbasf2.belle2.org/',
None),
371 'uproot': (
'https://uproot.readthedocs.io/en/stable/',
None)}
374def process_sig(app, what, name, obj, options, signature, return_annotation):
376 remove unhelpful 'self' arguments from methods.
378 if what ==
'method' and signature:
379 reg = re.compile(
'^\\( \\(.*\\)arg1')
380 signature = reg.sub(
'(', signature)
381 return (signature, return_annotation)
384def improve_docstring(obj):
386 Enhances docstrings of PyROOT objects/classes.
388 >>> improve_docstring(Belle2.Variable.Manager)
392 >>> variables = ROOT.Belle2.Variable.Manager
393 >>> improve_docstring(variables)
397 classname = obj.__name__
399 except AttributeError:
400 classname = obj.__class__.__name__
401 pyclass = obj.__class__
403 if '::' not in classname:
405 pos = classname.find(
'Belle2::')
406 classname = classname[pos:]
407 if pyclass.__doc__
is None:
410 pyclass.__name__ =
'Belle2.' + classname
412 from ROOT
import TClass
413 tclass = TClass(classname)
417 doxygen_url = f
'{basf2_doxygen_baseurl}/class'
418 doxygen_url +=
'_1_1'.join(classname.split(
'::'))
419 doxygen_url +=
'.html'
420 pyclass.__doc__ += f
'\n`Doxygen page for {classname} <{doxygen_url}>`_'
423 members = tclass.GetListOfMethods()
424 if members.GetEntries() > 0:
425 pyclass.__doc__ +=
'\n\nMember functions:'
428 pyclass.__doc__ += f
'\n * {f.GetReturnTypeName()} {f.GetName()}{f.GetSignature()}'
431 pyclass.__doc__ += f
' ({title})'
433 members = tclass.GetListOfAllPublicDataMembers()
434 if members.GetEntries() > 0:
435 pyclass.__doc__ +=
'\n\nPublic data members'
437 pyclass.__doc__ += f
'\n * {f.GetName()}'
440 pyclass.__doc__ += f
' ({title})'
443def skipmember(app, what, name, obj, skip, options):
445 This is executed before docstring processing,
446 so try improving them a bit.
449 improve_docstring(obj)
450 except AttributeError:
455def process_docstring(app, what, name, obj, options, lines):
457 convert doxygen syntax to sphinx
460 re.compile(
r'^( *)@param (.*?):? '):
r':param \2: ',
461 re.compile(
r'^( *)@returns? '):
r':return: ',
466 for reg, sub
in substitutions.items():
467 new = reg.sub(sub, new)
477 Install some event handlers to improve output.
479 app.connect(
'autodoc-process-signature', process_sig)
480 app.connect(
'autodoc-process-docstring', process_docstring)
481 app.connect(
'autodoc-skip-member', skipmember)
482 app.add_css_file(
'css/custom.css')