docs: generate documentation for library constants/flags

Author: jgriffiths

docs/source/conf.py

@@ -18,11 +18,11 @@ def preprocess_output_doc_line(l):
     if 'FIXED_SIZED_OUTPUT(' in l:
         parts = [p.strip() for p in l[len('FIXED_SIZED_OUTPUT('):-1].split(',')]
         len_param, param, size = parts
-        text = ':param {}: Size of ``{}``. Must be ``{}``.'.format(len_param, param, size)
+        text = ':param {}: Size of ``{}``. Must be `{}`.'.format(len_param, param, size)
     elif 'MAX_SIZED_OUTPUT(' in l:
         parts = [p.strip() for p in l[len('FIXED_SIZED_OUTPUT('):-1].split(',')]
         len_param, param, max_size = parts
-        text = ':param {}: Size of ``{}``. Passing ``{}`` will ensure the buffer is large enough.'.format(len_param, param, max_size)
+        text = ':param {}: Size of ``{}``. Passing `{}` will ensure the buffer is large enough.'.format(len_param, param, max_size)
     return '* ' + l if l else None, text
 
 def output_func(docs, func):
@@ -60,20 +60,39 @@ def extract_docs(infile, outfile):
 
     lines = [l.strip() for l in open(infile).readlines()]
     if DUMP_INTERNAL:
-        title = 'unused'
+        title, constant_title = 'unused', 'unused'
     else:
-        title = infile.split('wally_')[1][:-2].title().replace('_', '-') + ' Functions'
-    title_markup = '=' * len(title)
+        base_title = infile.split('wally_')[1][:-2].title().replace('_', '-')
+        title, constant_title = base_title + ' Functions', base_title + ' Constants'
+    title_markup, constant_markup = '=' * len(title), '-' * len(constant_title)
     output, current, func, state = [title, title_markup, ''], [], '', SCANNING
+    constants, last_one_liner = [' ', constant_title, constant_markup, ''], ''
 
     for l in lines:
         # Allow one-liner internal functions with no doc comments
         if DUMP_INTERNAL and state == SCANNING and l.startswith('WALLY_CORE_API'):
             state = FUNC
 
         if state == SCANNING:
-            if l.startswith('/**') and '*/' not in l:
-                current, func, state = [l[3:]], '', DOCS
+            if l.startswith('/***'):
+                mark, details = l[4:-2].strip().split(' ', 1)
+                constants.extend([f'.. _{mark}:', '', details, '^' *len(details)])
+            elif l.startswith('/**'):
+                if '*/' in l:
+                    last_one_liner = l[3:-2].strip()
+                else:
+                    current, func, state = [l[3:]], '', DOCS
+            elif l.startswith('#define ') and ' ' in l[len('#define '):]: # and '/*' not in l:
+                c, remainder = l[len('#define '):].strip().split(' ', 1)
+                if '/* ' in remainder:
+                    remainder = remainder.split('/* ')[0].strip()
+                if '/**' in remainder:
+                    last_one_liner = remainder.split('/**')[1][:-2]
+                constants.extend(['.. c:macro:: ' + c.strip(), ' ',
+                                  '    ' + last_one_liner.strip(), ''])
+                last_one_liner = ''
+            else:
+                last_one_liner = ''
         elif state == DOCS:
             if l == '*/':
                 state = FUNC
@@ -94,6 +113,8 @@ def extract_docs(infile, outfile):
                     current, func = '', ''
                 state = SCANNING
 
+    if len(constants) > 4:
+        output.extend(constants)
     with open(outfile, 'w') as f:
         f.write('\n'.join(output))