Switched documentation from asciidoc to rst, added doc autogeneration code for options

.gitignore

@@ -17,3 +17,4 @@ tests/__pycache__/
 
 mount/target
 mount.bcachefs
+doc/autogen/gen.csv

Makefile

@@ -73,7 +73,7 @@ else
 endif
 
 .PHONY: all
-all: bcachefs
+all: bcachefs bcachefs.5
 
 .PHONY: tests
 tests: tests/test_helper
@@ -89,6 +89,13 @@ TAGS:
 tags:
 	ctags -R .
 
+DOCSRC := gen.h bcachefs.5.rst
+DOCGENERATED := bcachefs.5 doc/autogen/gen.csv
+DOCDEPS := $(addprefix ./doc/autogen/,$(DOCSRC))
+bcachefs.5: $(DOCDEPS)  libbcachefs/opts.h
+	CC=$(CC) doc/autogen/gen.sh
+	rst2man doc/autogen/bcachefs.5.rst bcachefs.5
+
 SRCS=$(shell find . -type f -iname '*.c')
 DEPS=$(SRCS:.c=.d)
 -include $(DEPS)
@@ -118,9 +125,6 @@ endif
 # Rebuild the 'version' command any time the version string changes
 cmd_version.o : .version
 
-doc/bcachefs.5: doc/bcachefs.5.txt
-	a2x -f manpage doc/bcachefs.5.txt
-
 .PHONY: install
 install: INITRAMFS_HOOK=$(INITRAMFS_DIR)/hooks/bcachefs
 install: INITRAMFS_SCRIPT=$(INITRAMFS_DIR)/scripts/local-premount/bcachefs
@@ -137,7 +141,7 @@ install: bcachefs
 
 .PHONY: clean
 clean:
-	$(RM) bcachefs mount.bcachefs libbcachefs_mount.a tests/test_helper .version $(OBJS) $(DEPS)
+	$(RM) bcachefs mount.bcachefs libbcachefs_mount.a tests/test_helper .version $(OBJS) $(DEPS) $(DOCGENERATED)
 	$(RM) -rf mount/target
 
 .PHONY: deb

doc/autogen/bcachefs.5.rst

@@ -1,21 +1,23 @@
-BCACHEFS(5)
+========
-===========
+bcachefs
+========
 
-NAME
+--------------------------------------------------
-----
+bcachefs overview, user's manual and configuration
-bcachefs - bcachefs overview, user's manual and configuration
+--------------------------------------------------
+:Manual section: 5
 
 DESCRIPTION
 -----------
 Bcachefs is a multi device copy on write filesystem that supports
 
- Checksumming
+- Checksumming
- Compression
+- Compression
- Encryption
+- Encryption
- Reflink
+- Reflink
- Caching
+- Caching
- Replication
+- Replication
- Erasure coding (reed-solomon)
+- Erasure coding (reed-solomon)
 
 And more. This document is intended to be an overview of the various features
 and use cases.
@@ -31,8 +33,10 @@ 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).
 
- * TODO: include master list of options from opts.h
+.. csv-table:: Options
-#include "opts.mdwn"
+   :file: gen.csv
+   :header-rows: 1
+   :delim: ;
 
 Device management
 -----------------
@@ -58,6 +62,8 @@ group.
 
 For example, given disks formatted with these labels:
 
+.. code-block:: bash
+
   bcachefs format -g controller1.hdd.hdd1 /dev/sda	\
                   -g controller1.hdd.hdd2 /dev/sdb	\
                   -g controller1.ssd.ssd1 /dev/sdc	\
@@ -73,9 +79,9 @@ Data placement, caching
 
 The following options control which disks data is written to:
 
- * foreground_target
+- foreground_target
- * background_target
+- background_target
- * promote_target
+- promote_target
 
 The foreground_target option is used to direct writes from applications. The
 background_target option, if set, will cause data to be moved to that target in
@@ -86,7 +92,9 @@ a cached copy of the data being read to that target, if it doesn't exist.
 
 Together, these options can be used for writeback caching, like so:
 
-  foregroud_target=ssd
+.. code-block:: bash
+
+  foreground_target=ssd
   background_target=hdd
   promote_target=ssd
 
@@ -97,6 +105,8 @@ per-file options. This is done by setting the device's durability to 0.
 These options can all be set on individual files or directories. They can also
 be used to pin a specific file or directory to a specific device or target:
 
+.. code-block:: bash
+
   foreground_target=ssd
   background_target=
   promote_target=

doc/autogen/gen.h

@@ -0,0 +1,18 @@
+#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

@@ -0,0 +1,15 @@
+#!/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
+