diff --git a/.gitignore b/.gitignore
index eb1f1ee1..e4267676 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,3 +17,4 @@ tests/__pycache__/
 
 mount/target
 mount.bcachefs
+doc/autogen/gen.csv
diff --git a/Makefile b/Makefile
index 23cb6c07..1fbe4c49 100644
--- a/Makefile
+++ b/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
diff --git a/doc/bcachefs.5.txt b/doc/autogen/bcachefs.5.rst
similarity index 86%
rename from doc/bcachefs.5.txt
rename to doc/autogen/bcachefs.5.rst
index 291e2e35..6ba763b7 100644
--- a/doc/bcachefs.5.txt
+++ b/doc/autogen/bcachefs.5.rst
@@ -1,21 +1,23 @@
-BCACHEFS(5)
-===========
+========
+bcachefs
+========
 
-NAME
-----
-bcachefs - bcachefs overview, user's manual and configuration
+--------------------------------------------------
+bcachefs overview, user's manual and configuration
+--------------------------------------------------
+:Manual section: 5
 
 DESCRIPTION
 -----------
 Bcachefs is a multi device copy on write filesystem that supports
 
- Checksumming
- Compression
- Encryption
- Reflink
- Caching
- Replication
- Erasure coding (reed-solomon)
+- Checksumming
+- Compression
+- Encryption
+- Reflink
+- Caching
+- Replication
+- 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
-#include "opts.mdwn"
+.. csv-table:: Options
+   :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
- * background_target
- * promote_target
+- foreground_target
+- background_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=
diff --git a/doc/autogen/gen.h b/doc/autogen/gen.h
new file mode 100644
index 00000000..2a7e5001
--- /dev/null
+++ b/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
diff --git a/doc/autogen/gen.sh b/doc/autogen/gen.sh
new file mode 100755
index 00000000..ff9e64fe
--- /dev/null
+++ b/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
+