from collections import defaultdict from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.directives import ObjectDescription from sphinx.domains import Domain from sphinx.domains import Index from sphinx.roles import XRefRole from sphinx.util.nodes import make_refnode class KeywordDirective(ObjectDescription): has_content = True required_arguments = 1 def handle_signature(self, sig, signode): signode += addnodes.desc_name(text=sig) return sig def add_target_and_index(self, name_cls, sig, signode): signode['ids'].append('keyword' + '-' + sig) if 'noindex' not in self.options: crowbar = self.env.get_domain('crowbar') crowbar.add_keyword(sig) class KeywordIndex(Index): name = 'keyword' localname = 'Keyword Index' shortname = 'Keyword' def generate(self, docnames=None): content = defaultdict(list) # sort the list of recipes in alphabetical order recipes = self.domain.get_objects() recipes = sorted(recipes, key=lambda recipe: recipe[0]) # generate the expected output, shown below, from the above using the # first letter of the recipe as a key to group thing # # name, subtype, docname, anchor, extra, qualifier, description for name, dispname, typ, docname, anchor, _ in recipes: content[dispname[0].lower()].append( (dispname, 0, docname, anchor, docname, '', typ)) # convert the dict to the sorted list of tuples expected content = sorted(content.items()) return content, True class CrowbarDomain(Domain): name = 'crowbar' label = 'Crowbar' roles = { 'ref': XRefRole() } directives = { 'keyword': KeywordDirective, } indices = { KeywordIndex, } initial_data = { 'keywords': [], } def get_full_qualified_name(self, node): return '{}.{}'.format('keyword', node.arguments[0]) def get_objects(self): for obj in self.data['keywords']: yield(obj) def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): match = [(docname, anchor) for name, sig, typ, docname, anchor, prio in self.get_objects() if sig == target] if len(match) > 0: todocname = match[0][0] targ = match[0][1] return make_refnode(builder, fromdocname, todocname, targ, contnode, targ) else: print('Awww, found nothing') return None def add_keyword(self, signature): """Add a new keyword to the domain.""" name = '{}.{}'.format('keyword', signature) anchor = 'keyword-{}'.format(signature) # name, dispname, type, docname, anchor, priority self.data['keywords'].append( (name, signature, 'Keyword', self.env.docname, anchor, 0)) def setup(app): app.add_domain(CrowbarDomain) return { 'version': '0.1', 'parallel_read_safe': True, 'parallel_write_safe': True, }