Documentation fixup: made filenames more descriptive, switched parsing utility to python

5 files changed, 100 insertions, 37 deletions

diff --git a/doc/autogen/gen.h b/doc/autogen/gen.h
deleted file mode 100644
index 2a7e5001..00000000
--- a/doc/autogen/gen.h
+++ /dev/null
@@ -1,18 +0,0 @@
-#include "../../libbcachefs/opts.h"
-
-/**
- * generate tables from definitions in opt.h
- */
-
-#define NULL (null)
-
-FMT_START_SECTION
-
-FMT_START_LINE Name ; Data Type ; Type Description ; Description ; Usage Flag FMT_END_LINE
-
-#define x(_name, _shortopt, _type, _in_mem_type, _mode, _sb_opt, _idk1, _idk2)\
-    FMT_START_LINE _name ; _shortopt ; _idk1 ; _idk2 ; _type FMT_END_LINE
-    BCH_OPTS()
-#undef x
-
-FMT_END_SECTION
diff --git a/doc/autogen/gen.sh b/doc/autogen/gen.sh
deleted file mode 100755
index ff9e64fe..00000000
--- a/doc/autogen/gen.sh
+++ /dev/null
@@ -1,15 +0,0 @@
-#!/bin/sh
-# Pull options from opts.h into a csv file for generating documentation
-
-$CC doc/autogen/gen.h -I libbcachefs -I include -E 2>/dev/null  \
-	| sed -n '/FMT_START_SECTION/,/FMT_END_SECTION/p'       \
-	| tr '\n' ' '                                           \
-	| sed -e 's/FMT_START_LINE/\n/g;' 			\
-		-e 's/FMT_END_LINE//g;' 			\
-		-e 's|\\n||g;'					\
-		-e 's/"//g;'					\
-		-e 's/OPT_//g;' 				\
-		-e 's/[ \t]*$//g'    				\
-	| grep -v -e FMT_START_SECTION -e FMT_END_SECTION	\
-	> doc/autogen/gen.csv
-
diff --git a/doc/autogen/bcachefs.5.rst b/doc/bcachefs.5.rst.tmpl
index 6ba763b7..7b5e1ce7 100644
--- a/doc/autogen/bcachefs.5.rst
+++ b/doc/bcachefs.5.rst.tmpl
@@ -33,10 +33,9 @@ set on individual files and directories, via the bcachefs setattr command (which
 internally mostly works via the extended attribute interface, but the setattr
 command takes care to propagate options to children correctly).
 
-.. csv-table:: Options
-   :file: gen.csv
-   :header-rows: 1
-   :delim: ;
+OPTIONS
+-------
+OPTIONS_TABLE
 
 Device management
 -----------------
diff --git a/doc/macro2rst.py b/doc/macro2rst.py
new file mode 100755
index 00000000..e80f7edb
--- /dev/null
+++ b/doc/macro2rst.py
@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+'''
+A utility script for generating documentation.
+
+Preprocessor macro output from opts_macro.h is parsed and combined with
+bcachefs.5.rst.tmpl to generate bcachefs.5.rst.
+
+>=python3.6
+'''
+
+import sys
+import re
+
+INDENT = '       '
+TEMPLATE = './doc/bcachefs.5.rst.tmpl'
+RST_FILE= './doc/bcachefs.5.rst'
+SANITIZE_CHARS = [
+            '\\\\n',
+            '\\n',
+            '  ',
+            '"',
+            '\\',
+        ]
+
+def sanitize(text):
+    '''
+    Parses opts_macro.h preprocessor output
+    :param text: text to sanitize
+    :type text: str
+    :returns: a list of options
+    :rtype: list
+    '''
+
+    args = []
+    reg = re.search('FMT_START_SECTION(.*)FMT_END_SECTION', text,
+            flags=re.DOTALL)
+    if not reg:
+        raise re.error('no text found')
+
+    # decoding would probably be better, but this works
+    for char in SANITIZE_CHARS:
+        text = text.replace(char, '')
+
+    text = re.split(r'FMT_END_LINE', text)
+
+    # this seemed easier than getting preprocessor macros to play nice
+    # with python's builtin csv module
+    for line in text:
+        vals = line.split(';')
+        if not vals:
+            continue
+        if len(vals) != 4:
+            continue
+        vals = list(map(str.strip, vals))
+        name, is_bool, desc, arg_name = vals
+
+        # this macro value from opts.h indicates that no values are passed
+        if is_bool == 'OPT_BOOL()':
+            args.append(f'--{name}\n{INDENT}{desc}')
+        else:
+            args.append(f'--{name} <{arg_name}>\n{INDENT}{desc}')
+    if not args:
+        raise re.error('no args found, likely parsing error')
+
+    return args
+
+
+def main():
+    ''' Transform stdin to option list and write templated output to new file '''
+    out = ''
+
+    stdin = sys.stdin.read()
+    opts = sanitize(stdin)
+    opts = '\n'.join(opts)
+
+    # Insert into template
+    with open(TEMPLATE, 'r') as in_handle:
+        in_handle = in_handle.read()
+    out = in_handle.replace('OPTIONS_TABLE', opts)
+    with open(RST_FILE, 'w') as out_handle:
+        out_handle.write(out)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/doc/opts_macro.h b/doc/opts_macro.h
new file mode 100644
index 00000000..9172802a
--- /dev/null
+++ b/doc/opts_macro.h
@@ -0,0 +1,12 @@
+#include "../libbcachefs/opts.h"
+
+/**
+ * generate tables from definitions in opt.h
+ */
+
+#define NULL (null)
+
+FMT_START_SECTION
+#define x(_name, _shortopt, _type, _in_mem_type, _mode, _sb_opt, _desc , _usage)\
+_name;_in_mem_type;_usage;_desc FMT_END_LINE
+BCH_OPTS() FMT_END_SECTION