22 sys.path.insert(0, os.path.abspath(
"extensions"))
38 'sphinx.ext.intersphinx',
42 'sphinx.ext.napoleon',
43 'sphinx.ext.viewcode',
44 'sphinx.ext.autosectionlabel',
48 'IPython.sphinxext.ipython_console_highlighting',
51 nbsphinx_allow_errors =
True
56 nbsphinx_custom_formats = {
57 '.doc.jupy.py':
lambda s: jupytext.reads(s,
'.py'),
64 autosectionlabel_prefix_document =
True
65 suppress_warnings = [
'autosectionlabel.*']
68 templates_path = [
'_sphinxtemplates']
73 source_suffix =
'.rst'
83 copyright =
'Belle II Collaboration'
84 author =
'Belle II Software Group'
91 version = subprocess.check_output([
"git",
"rev-parse",
"--short",
"HEAD"]).decode().strip()
93 basf2_repository =
"https://stash.desy.de/projects/B2/repos/basf2"
94 basf2_commitid = subprocess.check_output([
"git",
"rev-parse",
"HEAD"]).decode().strip()
95 basf2_jira =
"https://agira.desy.de"
98 release = os.environ.get(
'BELLE2_RELEASE',
'development')
100 release =
'development'
103 keep_warnings = release ==
"development"
104 nitpicky = keep_warnings
108 for entry
in [
'cppyy.gbl.TObject',
'cppyy.gbl.TFile',
'ROOT.TFile']:
109 nitpick_ignore.append((
'py:class', entry))
110 for entry
in [
'int',
'bool',
'list',
'str',
'object',
'None',
'LogConfig',
'ModuleStatistics']:
111 nitpick_ignore.append((
'py:class', entry +
' :'))
129 exclude_patterns = [
'.*',
'_sphinxbuild',
'Thumbs.db',
'build',
'include',
'lib',
'bin',
'modules',
'data',
'site_scons']
131 if tags.has(
'light'):
132 light_packages = set([entry.strip(
'/')
for entry
in open(
'../../.light').read().split()
if entry.endswith(
'/')])
133 for entry
in os.listdir(
"../../"):
134 if entry.find(
'.') > -1
or os.path.isfile(entry)
or entry
in exclude_patterns
or entry
in light_packages:
136 exclude_patterns.append(entry)
141 exclude_patterns.remove(
"build")
142 exclude_patterns += [
'build/html',
'build/latex',
'build/json',
'build/Linux*']
144 exclude_patterns += [
'**/*.ipynb',
'*.ipynb']
162 pygments_style =
'sphinx'
171 todo_include_todos =
False
182 html_theme =
'sphinx_rtd_theme'
190 html_theme_path = [
"_themes", ]
201 html_logo =
"b2logo.svg"
211 html_static_path = [
'_sphinxstatic']
276 htmlhelp_basename =
'basf2doc'
282 'papersize':
'a4paper',
288 'preamble':
'\\setcounter{tocdepth}{2}',
298 (master_doc,
'basf2.tex',
'Belle 2 Software Documentation',
304 latex_logo =
"belle2-logo.pdf"
308 latex_use_parts =
True
309 latex_show_urls =
'footnote'
310 latex_show_pagerefs =
True
330 (master_doc,
'basf2',
'basf2 Documentation',
343 texinfo_documents = [
344 (master_doc,
'basf2',
'basf2 Documentation',
345 author,
'basf2',
'One line description of project.',
362 intersphinx_mapping = {
'python': (
'https://docs.python.org/3.6',
None)}
365 def process_sig(app, what, name, obj, options, signature, return_annotation):
367 remove unhelpful 'self' arguments from methods.
369 if what ==
'method' and signature:
370 reg = re.compile(
'^\\( \\(.*\\)arg1')
371 signature = reg.sub(
'(', signature)
372 return (signature, return_annotation)
375 def improve_docstring(obj):
377 Enhances docstrings of PyROOT objects/classes.
379 >>> improve_docstring(Belle2.Variable.Manager)
383 >>> variables = ROOT.Belle2.Variable.Manager
384 >>> improve_docstring(variables)
388 classname = obj.__name__
390 except AttributeError:
391 classname = obj.__class__.__name__
392 pyclass = obj.__class__
394 if '::' not in classname:
396 pos = classname.find(
'Belle2::')
397 classname = classname[pos:]
398 if pyclass.__doc__
is None:
401 pyclass.__name__ =
'Belle2.' + classname
403 from ROOT
import TClass
404 tclass = TClass(classname)
408 doxygen_url =
'https://software.belle2.org/development/class'
409 doxygen_url +=
'_1_1'.join(classname.split(
'::'))
410 doxygen_url +=
'.html'
411 pyclass.__doc__ +=
'\n`Doxygen page for %s <%s>`_' % (classname, doxygen_url)
414 members = tclass.GetListOfMethods()
415 if members.GetEntries() > 0:
416 pyclass.__doc__ +=
'\n\nMember functions:'
419 pyclass.__doc__ +=
'\n * %s %s%s' % (f.GetReturnTypeName(), f.GetName(), f.GetSignature())
422 pyclass.__doc__ +=
' (%s)' % (title)
424 members = tclass.GetListOfAllPublicDataMembers()
425 if members.GetEntries() > 0:
426 pyclass.__doc__ +=
'\n\nPublic data members'
428 pyclass.__doc__ +=
'\n * %s' % (f.GetName())
431 pyclass.__doc__ +=
' (%s)' % (title)
434 def skipmember(app, what, name, obj, skip, options):
436 This is executed before docstring processing,
437 so try improving them a bit.
440 improve_docstring(obj)
441 except AttributeError:
446 def process_docstring(app, what, name, obj, options, lines):
448 convert doxygen syntax to sphinx
451 re.compile(
r'^( *)@param (.*?):? '):
r':param \2: ',
452 re.compile(
r'^( *)@returns? '):
r':return: ',
457 for reg, sub
in substitutions.items():
458 new = reg.sub(sub, new)
468 Install some event handlers to improve output.
470 app.connect(
'autodoc-process-signature', process_sig)
471 app.connect(
'autodoc-process-docstring', process_docstring)
472 app.connect(
'autodoc-skip-member', skipmember)
473 app.add_css_file(
'css/custom.css')
479 from sphinx.ext
import autodoc
481 old_directive_header = autodoc.PropertyDocumenter.add_directive_header
485 def _fixed_directive_header(*args, **argk):
486 """Catch the ValueError and ignore it as done in https://github.com/sphinx-doc/sphinx/pull/9190"""
488 old_directive_header(*args, **argk)
494 autodoc.PropertyDocumenter.add_directive_header = _fixed_directive_header