From 7ab27eeb539aca74c551d79fe082156dbaf76000 Mon Sep 17 00:00:00 2001
From: Peter Hodge <peter.hodge84@gmail.com>
Date: Wed, 25 Jul 2018 14:07:55 +1000
Subject: [PATCH] DOC: add support for intro sections in api docs

---
 scripts/gen_api_vimdoc.py | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/scripts/gen_api_vimdoc.py b/scripts/gen_api_vimdoc.py
index 0bbc3706c6..4e86f15b37 100755
--- a/scripts/gen_api_vimdoc.py
+++ b/scripts/gen_api_vimdoc.py
@@ -413,10 +413,26 @@ def gen_docs(config):
         sys.exit(p.returncode)
 
     sections = {}
+    intros = {}
     sep = '=' * text_width
 
     base = os.path.join(out_dir, 'xml')
     dom = minidom.parse(os.path.join(base, 'index.xml'))
+
+    # generate docs for section intros
+    for compound in dom.getElementsByTagName('compound'):
+        if compound.getAttribute('kind') != 'group':
+            continue
+
+        groupname = get_text(find_first(compound, 'name'))
+        groupxml = os.path.join(base, '%s.xml' % compound.getAttribute('refid'))
+
+        desc = find_first(minidom.parse(groupxml), 'detaileddescription')
+        if desc:
+            doc = parse_parblock(desc)
+            if doc:
+                intros[groupname] = doc
+
     for compound in dom.getElementsByTagName('compound'):
         if compound.getAttribute('kind') != 'file':
             continue
@@ -437,6 +453,11 @@ def gen_docs(config):
                     name = name.title()
 
                 doc = ''
+
+                intro = intros.get('api-%s' % name.lower())
+                if intro:
+                    doc += '\n\n' + intro
+
                 if functions:
                     doc += '\n\n' + functions