From 686aa4ec1d3fdf2e624e9489d9fbf0fcefc34049 Mon Sep 17 00:00:00 2001
From: Jakob Stoklund Olesen <jolesen@mozilla.com>
Date: Fri, 23 Sep 2016 16:41:14 -0700
Subject: [PATCH] Add an autoinstgroup Sphinx directive.

This directive documents an instruction group and lists all instructions
contained in the group, whether they have been documented or not.
---
 docs/cton_domain.py | 36 ++++++++++++++++++++++++++++++++++++
 docs/langref.rst    | 13 +++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/docs/cton_domain.py b/docs/cton_domain.py
index ba762b4df3..b45aa5e677 100644
--- a/docs/cton_domain.py
+++ b/docs/cton_domain.py
@@ -173,6 +173,10 @@ class CtonInst(CtonObject):
         return name
 
 
+class CtonInstGroup(CtonObject):
+    """A Cretonne IL instruction group."""
+
+
 class CretonneDomain(Domain):
     """Cretonne domain for intermediate language objects."""
     name = 'cton'
@@ -186,11 +190,13 @@ class CretonneDomain(Domain):
     directives = {
         'type': CtonType,
         'inst': CtonInst,
+        'instgroup': CtonInstGroup,
     }
 
     roles = {
         'type': XRefRole(),
         'inst': XRefRole(),
+        'instgroup': XRefRole(),
     }
 
     initial_data = {
@@ -327,9 +333,39 @@ class InstDocumenter(sphinx.ext.autodoc.Documenter):
                         sourcename)
 
 
+class InstGroupDocumenter(sphinx.ext.autodoc.ModuleLevelDocumenter):
+    # Invoke with .. autoinstgroup::
+    objtype = 'instgroup'
+    # Convert into cton:instgroup directives
+    domain = 'cton'
+    directivetype = 'instgroup'
+
+    @classmethod
+    def can_document_member(cls, member, membername, isattr, parent):
+        return False
+
+    def format_name(self):
+        return "{}.{}".format(self.modname, ".".join(self.objpath))
+
+    def add_content(self, more_content, no_docstring=False):
+        super(InstGroupDocumenter, self).add_content(
+                more_content, no_docstring)
+        sourcename = self.get_sourcename()
+        indexed = self.env.domaindata['cton']['objects']
+
+        names = [inst.name for inst in self.object.instructions]
+        names.sort()
+        for name in names:
+            if name in indexed:
+                self.add_line(u':cton:inst:`{}`'.format(name), sourcename)
+            else:
+                self.add_line(u'``{}``'.format(name), sourcename)
+
+
 def setup(app):
     app.add_domain(CretonneDomain)
     app.add_autodocumenter(TypeDocumenter)
     app.add_autodocumenter(InstDocumenter)
+    app.add_autodocumenter(InstGroupDocumenter)
 
     return {'version': '0.1'}
diff --git a/docs/langref.rst b/docs/langref.rst
index 10385cb7f4..99a6e1ca62 100644
--- a/docs/langref.rst
+++ b/docs/langref.rst
@@ -308,6 +308,7 @@ Quiet NaNs
 Signaling NaNs
     Displayed as ``-sNaN:0xT``.
 
+
 Control flow
 ============
 
@@ -814,6 +815,18 @@ Conversion operations
 .. autoinst:: fcvt_from_uint
 .. autoinst:: fcvt_from_sint
 
+
+Base instruction group
+======================
+
+All of the shared instructions are part of the :instgroup:`base` instruction
+group.
+
+.. autoinstgroup:: cretonne.base.instructions
+
+Target ISAs may define further instructions in their own instruction groups.
+
+
 Glossary
 ========