basf2domain.py

 
from docutils import nodes
from docutils.parsers.rst import directives
from sphinx import addnodes
from sphinx.roles import XRefRole
from sphinx.directives import ObjectDescription
from sphinx.domains import Domain, ObjType, Index
from sphinx.util.docfields import TypedField, Field
from sphinx.util.nodes import make_refnode
from sphinx.util import logging
logger = logging.getLogger(__name__)
 
 
class Basf2Object(ObjectDescription):
    """
    A basf2 x-ref directive registered with Sphinx.add_object_type().
    Basically copied together from sphinxcontrib-domaintools and sphinxcontrib-adadomain.
    """
 

 
    doc_field_types = {
        TypedField("parameter", label="Parameters", names=("param", "parameter", "arg", "argument"),
                   typenames=("paramtype", "type"), typerolename=None, can_collapse=True),
        Field('returnvalue', label='Returns', has_arg=False,
              names=('returns', 'return')),
    }
 
    def handle_signature(self, sig, signode):
        signode.clear()
 
        # check if we have arguments
        try:
            name, args = sig.split("(", 1)
        except ValueError:
            name = sig
            args = None
 
        # Add the name of the signature
        name = name.strip()
        signode += addnodes.desc_name(name, name)
 
        # if there was a opening parenthesis add all the arguments to the
        # parameter list, separate them by comma
        if args:
            paramlist = addnodes.desc_parameterlist()
            for arg in (e.strip() for e in args[:-1].split(",")):
                if not arg:
                    continue
                paramlist += addnodes.desc_parameter(arg, arg)
            signode += paramlist
 
        # return the object name for referencing
        return name
 

 
    def add_target_and_index(self, name, sig, signode):
        # Create a full id from objtype and name
        targetname = f'{self.objtype}-{name}'
        # and append the id to the object node
        signode['ids'].append(targetname)
        self.state.document.note_explicit_target(signode)
 
        # remember the name -> (document, targetname) mapping in the domain data
        # dictionary so that we can use it to resolve x-refs
        ddata = self.env.domaindata["b2"][self.objtype + 's']
 
        if name in ddata:
            # already exists, give warning
            logger.warn(f"Duplicate description of basf2 {self.objtype} {name}, " +
                        "Other instance in " + self.env.doc2path(ddata[name][0]) +
                        ", please add ':noindex:' to one",
                        location=(self.env.docname, self.lineno))
        else:
            ddata[name] = (self.env.docname, targetname)
 
 
class Basf2ModuleIndex(Index):
    """Create an alphabetic index of all modules"""
    
    name = "modindex"
    localname = "basf2 Module Index"
    shortname = "basf2 modules"
 
    def generate(self, docnames=None):
        content = {}
        modules = self.domain.data["modules"].items()
        for modname, (docname, target) in sorted(modules):
            letter = modname[0].upper()
            content.setdefault(letter, [])
            content[letter].append([modname, 0, docname, target, "", "", ""])
        return list(content.items()), False
    
 
 
class Basf2VariableIndex(Index):
    """Create an alphabetic index of all variables"""
    
    name = "varindex"
    localname = "basf2 Variable Index"
    shortname = "basf2 variables"
 
    def generate(self, docnames=None):
        content = {}
        modules = self.domain.data["variables"].items()
        modules = sorted(modules, key=lambda x: x[0].lower())
        for modname, (docname, target) in modules:
            letter = modname[0].upper()
            content.setdefault(letter, [])
            content[letter].append([modname, 0, docname, target, "", "", ""])
        return list(content.items()), False
    
 
 
class Basf2VariableObject(Basf2Object):
    # extend the option spec to accept a source: URL
    option_spec = Basf2Object.option_spec.copy() if hasattr(Basf2Object, "option_spec") else {}
    option_spec.update({
        "source": directives.uri,   # support :source: option
    })
 
    def handle_signature(self, sig, signode):
        # Call parent to parse the signature and add the variable name
        name = super().handle_signature(sig, signode)
 
        # If :source: option is given, add a [source] link inline
        if "source" in self.options:
            uri = self.options["source"]
            linknode = nodes.reference('', '[source]', refuri=uri, classes=['var-source-link'])
            signode += linknode
 
        return name
 
 
class Basf2Domain(Domain):
    """basf2 Software Domain"""
    
    name = "b2"
    label = "Belle II Software"
    object_types = {
        "module": ObjType("module", "mod"),
        "variable": ObjType("variable", "var")
    }
 
    directives = {
        "module": Basf2Object,
        "variable": Basf2VariableObject,
    }
    roles = {
        "mod": XRefRole(),
        "var": XRefRole(),
    }
    initial_data = {
        "modules": {},
        "variables": {},
    }
    indices = [
        Basf2ModuleIndex,
        Basf2VariableIndex,
    ]
    
 
    def clear_doc(self, docname):
        """Remove the existing domain data for a given document name"""
        for t in "modules", "variables":
            try:
                for name, (doc, target) in list(self.data[t].items()):
                    if doc == docname:
                        del self.data[t][name]
            except Exception:
                pass
 
    
    def get_objects(self):
        for i, type in enumerate(["modules", "variables"]):
            for name, (docname, target) in self.data[type].items():
                yield (name, name, type, docname, target, i)
 
    def get_type_name(self, type, primary=False):
        # never prepend "Default"
        return type.lname
 
    def resolve_xref(self, env, fromdocname, builder,
                     typ, target, node, contnode):
        t = {"mod": "modules", "var": "variables"}[typ]
        try:
            docname, labelid = self.data[t][target]
            return make_refnode(builder, fromdocname, docname,
                                labelid, contnode)
        except Exception:
            return None