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

.gitignore

@@ -18,4 +18,4 @@ tests/__pycache__/
 
 mount/target
 mount.bcachefs
-doc/autogen/gen.csv
+doc/bcachefs.5.rst

Makefile

@@ -89,12 +89,13 @@ TAGS:
 tags:
 	ctags -R .
 
-DOCSRC := gen.h bcachefs.5.rst
-DOCGENERATED := bcachefs.5 doc/autogen/gen.csv
-DOCDEPS := $(addprefix ./doc/autogen/,$(DOCSRC))
+DOCSRC := opts_macro.h bcachefs.5.rst.tmpl
+DOCGENERATED := bcachefs.5 doc/bcachefs.5.rst
+DOCDEPS := $(addprefix ./doc/,$(DOCSRC))
 bcachefs.5: $(DOCDEPS)  libbcachefs/opts.h
-	CC=$(CC) doc/autogen/gen.sh
-	rst2man doc/autogen/bcachefs.5.rst bcachefs.5
+	$(CC) doc/opts_macro.h -I libbcachefs -I include -E 2>/dev/null	\
+		| doc/macro2rst.py
+	rst2man doc/bcachefs.5.rst bcachefs.5
 
 SRCS=$(shell find . -type f -iname '*.c')
 DEPS=$(SRCS:.c=.d)

doc/autogen/gen.h

@@ -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

doc/autogen/gen.sh

@@ -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
-

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
 -----------------

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()

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