From e3433f433ca0ee33959708cb8bcbd4263215eefc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@koumbit.org>
Date: Wed, 30 Sep 2015 17:30:13 -0400
Subject: [PATCH 1/2] generate usage include files only as needed

right now, the update_usage script regenerates the usage files at
every call

by moving this into the makefile, we make those files be generated
only when the source file change, which makes testing docs much faster
---
 docs/Makefile        | 16 ++++++++++++++--
 docs/update_usage.sh | 13 -------------
 2 files changed, 14 insertions(+), 15 deletions(-)
 delete mode 100755 docs/update_usage.sh

diff --git a/docs/Makefile b/docs/Makefile
index 387195a2a..1aaf1cf7e 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -36,8 +36,7 @@ help:
 clean:
 	-rm -rf $(BUILDDIR)/*
 
-html:
-	./update_usage.sh
+html: usage
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@@ -140,3 +139,16 @@ gh-io: html
 
 inotify: html
 	while inotifywait -r . --exclude usage.rst --exclude '_build/*' ; do make html ; done
+
+# generate list of targets
+usage: $(shell borg help | grep -A1 "Available commands:" | tail -1 | sed 's/[{} ]//g;s/,\|^/.rst.inc usage\//g;s/^.rst.inc//;s/usage\/help//')
+
+# generate help file based on usage
+usage/%.rst.inc: ../borg/archiver.py
+	printf ".. _borg_$*:\n\n" > $@
+	printf "borg $*\n" >> $@
+	echo -n borg $* | tr 'a-z- ' '-' >> $@
+	printf "\n::\n\n" >> $@
+	borg help $* --usage-only | sed -e 's/^/    /' >> $@
+	printf "\nDescription\n~~~~~~~~~~~\n" >> $@
+	borg help $* --epilog-only >> $@
diff --git a/docs/update_usage.sh b/docs/update_usage.sh
deleted file mode 100755
index 9e79f4e88..000000000
--- a/docs/update_usage.sh
+++ /dev/null
@@ -1,13 +0,0 @@
-#!/bin/bash
-if [ ! -d usage ]; then
-  mkdir usage
-fi
-for cmd in change-passphrase check create delete extract info init list mount prune serve; do
-  FILENAME="usage/$cmd.rst.inc"
-  LINE=`echo -n borg $cmd | tr 'a-z- ' '-'`
-  echo -e ".. _borg_$cmd:\n" > $FILENAME
-  echo -e "borg $cmd\n$LINE\n::\n\n" >> $FILENAME
-  borg help $cmd --usage-only | sed -e 's/^/    /' >> $FILENAME
-  echo -e "\nDescription\n~~~~~~~~~~~\n" >> $FILENAME
-  borg help $cmd --epilog-only >> $FILENAME
-done

From 50e7d0f345c85db9a86e0ea2c8991e61095ddbf3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@koumbit.org>
Date: Wed, 30 Sep 2015 17:42:18 -0400
Subject: [PATCH 2/2] more human-readable output in usage generation

---
 docs/Makefile | 15 ++++++++-------
 docs/api.rst  |  6 ++++++
 2 files changed, 14 insertions(+), 7 deletions(-)
 create mode 100644 docs/api.rst

diff --git a/docs/Makefile b/docs/Makefile
index 1aaf1cf7e..1f3f7d76c 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -145,10 +145,11 @@ usage: $(shell borg help | grep -A1 "Available commands:" | tail -1 | sed 's/[{}
 
 # generate help file based on usage
 usage/%.rst.inc: ../borg/archiver.py
-	printf ".. _borg_$*:\n\n" > $@
-	printf "borg $*\n" >> $@
-	echo -n borg $* | tr 'a-z- ' '-' >> $@
-	printf "\n::\n\n" >> $@
-	borg help $* --usage-only | sed -e 's/^/    /' >> $@
-	printf "\nDescription\n~~~~~~~~~~~\n" >> $@
-	borg help $* --epilog-only >> $@
+	@echo generating usage for $*
+	@printf ".. _borg_$*:\n\n" > $@
+	@printf "borg $*\n" >> $@
+	@echo -n borg $* | tr 'a-z- ' '-' >> $@
+	@printf "\n::\n\n" >> $@
+	@borg help $* --usage-only | sed -e 's/^/    /' >> $@
+	@printf "\nDescription\n~~~~~~~~~~~\n" >> $@
+	@borg help $* --epilog-only >> $@
diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 000000000..c535aa970
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,6 @@
+Borg Backup API documentation
+=============================
+
+.. automodule:: borg
+   :members:
+   :undoc-members: