Belle II Software  release-05-01-25
basf2domain.py
1 from sphinx import addnodes
2 from sphinx.roles import XRefRole
3 from sphinx.directives import ObjectDescription
4 from sphinx.domains import Domain, ObjType, Index
5 from sphinx.util.docfields import TypedField, Field
6 from sphinx.util.nodes import make_refnode
7 from sphinx.util import logging
8 logger = logging.getLogger(__name__)
9 
10 
11 class Basf2Object(ObjectDescription):
12  """
13  A Basf2 x-ref directive registered with Sphinx.add_object_type().
14  Basically copied together from sphinxcontrib-domaintools and sphinxcontrib-adadomain.
15  """
16 
17  doc_field_types = {
18  TypedField("parameter", label="Parameters", names=("param", "parameter", "arg", "argument"),
19  typenames=("paramtype", "type"), typerolename=None, can_collapse=True),
20  Field('returnvalue', label='Returns', has_arg=False,
21  names=('returns', 'return')),
22  }
23 
24  def handle_signature(self, sig, signode):
25  signode.clear()
26 
27  # check fi we have arguments
28  try:
29  name, args = sig.split("(", 1)
30  except Exception as e:
31  name = sig
32  args = None
33 
34  # Add the name of the signature
35  name = name.strip()
36  signode += addnodes.desc_name(name, name)
37 
38  # if there was a opening parenthesis add all the arguments to the
39  # parameter list, separate them by comma
40  if args:
41  paramlist = addnodes.desc_parameterlist()
42  for arg in (e.strip() for e in args[:-1].split(",")):
43  if not arg:
44  continue
45  paramlist += addnodes.desc_parameter(arg, arg)
46  signode += paramlist
47 
48  # return the object name for referencing
49  return name
50 
51  def add_target_and_index(self, name, sig, signode):
52  # Create a full id from objtype and name
53  targetname = '%s-%s' % (self.objtype, name)
54  # and append the id to the object node
55  signode['ids'].append(targetname)
56  self.state.document.note_explicit_target(signode)
57 
58  # remember the name -> (document, targetname) mapping in the domain data
59  # dictionary so that we can use it to resolve x-refs
60  ddata = self.env.domaindata["b2"][self.objtype + 's']
61 
62  if name in ddata:
63  # already exists, give warning
64  logger.warn("Duplicate description of basf2 %s %s, " % (self.objtype, name) +
65  "Other instance in " + self.env.doc2path(ddata[name][0]) +
66  ", please add ':noindex:' to one",
67  location=(self.env.docname, self.lineno))
68  else:
69  ddata[name] = (self.env.docname, targetname)
70 
71 
72 class Basf2ModuleIndex(Index):
73  """Create an alphabetic index of all modules"""
74  name = "modindex"
75  localname = "Basf2 Module Index"
76  shortname = "basf2 modules"
77 
78  def generate(self, docnames=None):
79  content = {}
80  modules = self.domain.data["modules"].items()
81  for modname, (docname, target) in sorted(modules):
82  letter = modname[0].upper()
83  content.setdefault(letter, [])
84  content[letter].append([modname, 0, docname, target, "", "", ""])
85  return list(content.items()), False
86 
87 
88 class Basf2VariableIndex(Index):
89  """Create an alphabetic index of all variables"""
90  name = "varindex"
91  localname = "Basf2 Variable Index"
92  shortname = "basf2 variables"
93 
94  def generate(self, docnames=None):
95  content = {}
96  modules = self.domain.data["variables"].items()
97  modules = sorted(modules, key=lambda x: x[0].lower())
98  for modname, (docname, target) in modules:
99  letter = modname[0].upper()
100  content.setdefault(letter, [])
101  content[letter].append([modname, 0, docname, target, "", "", ""])
102  return list(content.items()), False
103 
104 
105 class Basf2Domain(Domain):
106  """Basf2 Software Domain"""
107  name = "b2"
108  label = "Belle 2 Software"
109  object_types = {
110  "module": ObjType("module", "mod"),
111  "variable": ObjType("variable", "var")
112  }
113 
114  directives = {
115  "module": Basf2Object,
116  "variable": Basf2Object,
117  }
118  roles = {
119  "mod": XRefRole(),
120  "var": XRefRole(),
121  }
122  initial_data = {
123  "modules": {},
124  "variables": {},
125  }
126  indices = [
127  Basf2ModuleIndex,
128  Basf2VariableIndex,
129  ]
130 
131  def clear_doc(self, docname):
132  """Remove the existing domain data for a given document name"""
133  for t in "modules", "variables":
134  try:
135  for name, (doc, target) in list(self.data[t].items()):
136  if doc == docname:
137  del self.data[t][name]
138  except Exception:
139  pass
140 
141  def get_objects(self):
142  for i, type in enumerate(["modules", "variables"]):
143  for name, (docname, target) in self.data[type].items():
144  yield(name, name, type, docname, target, i)
145 
146  def get_type_name(self, type, primary=False):
147  # never prepend "Default"
148  return type.lname
149 
150  def resolve_xref(self, env, fromdocname, builder,
151  typ, target, node, contnode):
152  t = {"mod": "modules", "var": "variables"}[typ]
153  try:
154  docname, labelid = self.data[t][target]
155  return make_refnode(builder, fromdocname, docname,
156  labelid, contnode)
157  except Exception:
158  return None
basf2domain.Basf2Domain
Definition: basf2domain.py:105
basf2domain.Basf2ModuleIndex
Definition: basf2domain.py:72
basf2domain.Basf2Object
Definition: basf2domain.py:11
basf2domain.Basf2VariableIndex
Definition: basf2domain.py:88
basf2domain.Basf2Domain.clear_doc
def clear_doc(self, docname)
Definition: basf2domain.py:131