diff --git a/Makefile b/Makefile
index d3d90fe..5b14a63 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: generate build test vet cover release clean
+.PHONY: generate build test vet cover release docs docs-clean clean release-bins
 .DEFAULT_GOAL := build
 
 ROOT := github.com/zrepl/zrepl
@@ -40,9 +40,24 @@ cover: artifacts
 $(ARTIFACTDIR):
 	mkdir -p "$@"
 
-release: $(ARTIFACTDIR) vet test docs
+$(ARTIFACTDIR)/docs: $(ARTIFACTDIR)
+	mkdir -p "$@"
+
+docs: $(ARTIFACTDIR)/docs
+	make -C docs \
+		html \
+		BUILDDIR=../artifacts/docs \
+
+docs-clean:
+	make -C docs \
+		clean \
+		BUILDDIR=../artifacts/docs
+
+release-bins: $(ARTIFACTDIR) vet test
 	GOOS=linux GOARCH=amd64   go build -o "$(ARTIFACTDIR)/zrepl-linux-amd64"
 	GOOS=freebsd GOARCH=amd64 go build -o "$(ARTIFACTDIR)/zrepl-freebsd-amd64"
 
-clean:
+release: release-bins docs
+
+clean: docs-clean
 	rm -rf "$(ARTIFACTDIR)"
diff --git a/clone_and_build.sh b/clone_and_build.sh
index 67838e2..7556321 100755
--- a/clone_and_build.sh
+++ b/clone_and_build.sh
@@ -41,6 +41,6 @@ step "Fetching dependencies using 'dep ensure'"
 dep ensure
 
 step "Making release"
-make release
+make release-bins
 
 step "Release artifacts are available in $(pwd)/artifacts"
diff --git a/docs/Makefile b/docs/Makefile
index 6638260..f85e18e 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -10,11 +10,11 @@ BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" -c sphinxconf $(SPHINXOPTS) $(O)
 
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -c sphinxconf $(SPHINXOPTS) $(O)
diff --git a/docs/publish.sh b/docs/publish.sh
index b2fd749..6a6ca0a 100755
--- a/docs/publish.sh
+++ b/docs/publish.sh
@@ -23,7 +23,7 @@ if [ ! -d "$PUBLICDIR" ]; then
     exit 1
 fi
 
-echo -n "PRESS ENTER to confirm you commited the docs changes to the zrepl repo"
+echo -n "PRESS ENTER to confirm you commited and pushed docs changes and tags to the zrepl repo"
 read
 
 pushd "$PUBLICDIR" 
@@ -47,9 +47,12 @@ popd
 
 echo "building site"
 set -e
-make clean
-make html
-rsync -a _build/html/ public_git/
+sphinx-versioning build \
+   --show-banner \
+   docs ./public_git \
+   -- -c sphinxconf # older conf.py throw errors because they used
+                    # version = subprocess.show_output(["git", "describe"])
+                    # which fails when building with sphinxcontrib-versioning
 set +e
 
 CURRENT_COMMIT=$(git rev-parse HEAD)
@@ -57,7 +60,7 @@ git status --porcelain
 if [[ "$(git status --porcelain)" != "" ]]; then
     CURRENT_COMMIT="${CURRENT_COMMIT}(dirty)" 
 fi
-COMMIT_MSG="sphinx render from publish.sh - `date -u` - ${CURRENT_COMMIT}"
+COMMIT_MSG="sphinx-versioning render from publish.sh - `date -u` - ${CURRENT_COMMIT}"
 
 pushd "$PUBLICDIR"
 
diff --git a/docs/conf.py b/docs/sphinxconf/conf.py
similarity index 96%
rename from docs/conf.py
rename to docs/sphinxconf/conf.py
index c7242a7..77d033e 100644
--- a/docs/conf.py
+++ b/docs/sphinxconf/conf.py
@@ -36,7 +36,7 @@ extensions = ['sphinx.ext.todo',
     'sphinx.ext.extlinks']
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['../_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -57,10 +57,9 @@ author = 'Christian Schwarz'
 # built documents.
 #
 # The short X.Y version.
-import subprocess
-version = subprocess.check_output(["git", "describe"]).decode("utf-8")
+#version = set by sphinxcontrib-versioning
 # The full version, including alpha/beta/rc tags.
-release = version
+#release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -97,10 +96,10 @@ html_theme = 'sphinx_rtd_theme'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['../_static']
 
 
-html_logo = '_static/zrepl.svg'
+html_logo = '../_static/zrepl.svg'
 
 # -- Options for HTMLHelp output ------------------------------------------