start to elaborate on syntax

1 files changed, 110 insertions, 0 deletions

diff --git a/_ext/crowbar_domain.py b/_ext/crowbar_domain.py
new file mode 100644
index 0000000..a5f2570
--- /dev/null
+++ b/_ext/crowbar_domain.py
@@ -0,0 +1,110 @@
+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,
+    }