24 sys.path.insert(0, os.path.abspath(
"extensions"))
40 'sphinx.ext.intersphinx',
44 'sphinx.ext.napoleon',
45 'sphinx.ext.viewcode',
46 'sphinx.ext.autosectionlabel',
50 'IPython.sphinxext.ipython_console_highlighting',
53 nbsphinx_allow_errors =
True
58 nbsphinx_custom_formats = {
59 '.doc.jupy.py':
lambda s: jupytext.reads(s,
'.py'),
66 autosectionlabel_prefix_document =
True
69 templates_path = [
'_sphinxtemplates']
74 source_suffix =
'.rst'
84 copyright =
'2010-2019, Belle II Collaboration'
85 author =
'Belle2 Software Group'
92 version = subprocess.check_output([
"git",
"rev-parse",
"--short",
"HEAD"]).decode().strip()
94 basf2_repository =
"https://stash.desy.de/projects/B2/repos/software"
95 basf2_commitid = subprocess.check_output([
"git",
"rev-parse",
"HEAD"]).decode().strip()
96 basf2_jira =
"https://agira.desy.de"
99 release = os.environ.get(
'BELLE2_RELEASE',
'development')
100 if release ==
'head':
101 release =
'development'
104 keep_warnings = release ==
"development"
105 nitpicky = keep_warnings
123 exclude_patterns = [
'.*',
'_sphinxbuild',
'Thumbs.db',
'build',
'include',
'lib',
'bin',
'modules',
'data',
'site_scons']
125 if tags.has(
'light'):
126 light_packages = set([entry.strip(
'/')
for entry
in open(
'../../.light').read().split()
if entry.endswith(
'/')])
127 for entry
in os.listdir(
"../../"):
128 if entry.find(
'.') > -1
or os.path.isfile(entry)
or entry
in exclude_patterns
or entry
in light_packages:
130 exclude_patterns.append(entry)
135 exclude_patterns.remove(
"build")
136 exclude_patterns += [
'build/html',
'build/latex',
'build/json',
'build/Linux*']
138 exclude_patterns += [
'**/*.ipynb',
'*.ipynb']
156 pygments_style =
'sphinx'
165 todo_include_todos =
False
176 html_theme =
'sphinx_rtd_theme'
181 html_theme_options = {
'stickysidebar':
True}
184 html_theme_path = [
"_themes", ]
195 html_logo =
"b2logo.svg"
205 html_static_path = [
'_sphinxstatic']
270 htmlhelp_basename =
'basf2doc'
276 'papersize':
'a4paper',
282 'preamble':
r'\setcounter{tocdepth}{2}',
292 (master_doc,
'basf2.tex',
'Belle 2 Software Documentation',
298 latex_logo =
"belle2-logo.pdf"
302 latex_use_parts =
True
303 latex_show_urls =
'footnote'
304 latex_show_pagerefs =
True
324 (master_doc,
'basf2',
'basf2 Documentation',
337 texinfo_documents = [
338 (master_doc,
'basf2',
'basf2 Documentation',
339 author,
'basf2',
'One line description of project.',
356 intersphinx_mapping = {
'python': (
'https://docs.python.org/3.6',
None)}
359 def process_sig(app, what, name, obj, options, signature, return_annotation):
361 remove unhelpful 'self' arguments from methods.
363 if what ==
'method' and signature:
364 reg = re.compile(
r'^\( \(.*\)arg1')
365 signature = reg.sub(
'(', signature)
366 return (signature, return_annotation)
369 def improve_docstring(obj):
371 Enhances docstrings of PyROOT objects/classes.
373 >>> improve_docstring(Belle2.Variable.Manager)
377 >>> variables = ROOT.Belle2.Variable.Manager
378 >>> improve_docstring(variables)
382 classname = obj.__name__
384 except AttributeError:
385 classname = obj.__class__.__name__
386 pyclass = obj.__class__
388 if '::' not in classname:
390 pos = classname.find(
'Belle2::')
391 classname = classname[pos:]
392 if pyclass.__doc__
is None:
395 pyclass.__name__ =
'Belle2.' + classname
397 from ROOT
import TClass
398 tclass = TClass(classname)
402 doxygen_url =
'https://b2-master.belle2.org/software/development/class'
403 doxygen_url +=
'_1_1'.join(classname.split(
'::'))
404 doxygen_url +=
'.html'
405 pyclass.__doc__ +=
'\n`Doxygen page for %s <%s>`_' % (classname, doxygen_url)
408 members = tclass.GetListOfMethods()
409 if members.GetEntries() > 0:
410 pyclass.__doc__ +=
'\n\nMember functions:'
413 pyclass.__doc__ +=
'\n * %s %s%s' % (f.GetReturnTypeName(), f.GetName(), f.GetSignature())
416 pyclass.__doc__ +=
' (%s)' % (title)
418 members = tclass.GetListOfAllPublicDataMembers()
419 if members.GetEntries() > 0:
420 pyclass.__doc__ +=
'\n\nPublic data members'
422 pyclass.__doc__ +=
'\n * %s' % (f.GetName())
425 pyclass.__doc__ +=
' (%s)' % (title)
428 def skipmember(app, what, name, obj, skip, options):
430 This is executed before docstring processing,
431 so try improving them a bit.
434 improve_docstring(obj)
435 except AttributeError:
440 def process_docstring(app, what, name, obj, options, lines):
442 convert doxygen syntax to sphinx
445 re.compile(
r'^( *)@param (.*?):? '):
r':param \2: ',
446 re.compile(
r'^( *)@returns? '):
r':return: ',
451 for reg, sub
in substitutions.items():
452 new = reg.sub(sub, new)
462 Install some event handlers to improve output.
464 app.connect(
'autodoc-process-signature', process_sig)
465 app.connect(
'autodoc-process-docstring', process_docstring)
466 app.connect(
'autodoc-skip-member', skipmember)
467 app.add_css_file(
'css/custom.css')