diff --git a/docs/Makefile b/docs/Makefile
index 3999c01b40..24f9502a87 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -7,6 +7,7 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
+AUTODOCDIR = $(SOURCEDIR)/api
 
 EVDIR ?= $(realpath ../evennia)
 EVGAMEDIR ?= $(realpath ../../gamedir)
@@ -23,48 +24,51 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	make help
-	# @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Evennia - custom commands
 
 install:
 	@pip install -r requirements.txt
 
-check-env:
-	@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) bash -e checkenv.sh
-
-# build only the api-autodoc index
+# build / update only the api-autodoc index
 autodoc-index:
 	@sphinx-apidoc -f -o $(SOURCEDIR)/api/ $(EVDIR)
 
 api-build:
 	@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html/api"
 
+clean:
+	@rm -Rf $(BUILDDIR)
+	@git clean -f -d docs/
+	@echo "Cleaned old build dir and leftover files."
+
+
+# multiversion release builds
+
+mv-check-env:
+	@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) bash -e checkenv.sh multiversion
+
+# we must commit the index before it's made available to multiversion 
+mv-autodoc-index:
+	@sphinx-apidoc -f -o $(SOURCEDIR)/api/ $(EVDIR)
+	git commit -a -m "Updated API autodoc index."
+
 multiversion-build:
 	@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html"
 
-clean:
-	@rm -Rf $(BUILDDIR)
-	@git clean -f -d
-	@echo "Cleaned old build dir and leftover files."
-
-local:
-	make check-env
-	make clean
-	make autodoc-index
-	make multiversion-build
-
-deploy:
+mv-deploy:
 	@bash -e deploy.sh
 
-# build and prepare the docs for release
-release:
-	make check-env
+mv-local:
+	make mv-check-env
 	make clean
-	make autodoc-index
+	make mv-autodoc-index
 	make multiversion-build
-	make deploy
-	make clean
+
+# build and prepare the docs for release
+mv-release:
+	make mv-local
+	# make mv-deploy
 	@echo ""
 	@echo "Deployment complete."
diff --git a/docs/README.md b/docs/README.md
index 45bb89e551..6f7c9108ae 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,6 +1,27 @@
 # evennia-docs
 Documentation for the Evennia MUD creation system.
 
-This is very much WIP. We are still experimenting with solutions. Don't use or contribute yet.
+The live documentation is available at `https://evennia.github.io/evennia/`.
 
-The live documentation will be available at `https://evennia.github.io/evennia-docs`.
+# building the docs
+
+## Prerequisits
+
+- Clone the evennia repository.
+- Follow the normal Evennia Getting-Started instructions. Use a virtualenv and create
+a new game folder called `gamedir` at the same level as your `evennia` repo and run migrations in it.
+
+```
+  (top)
+  |
+  ----- evennia/
+  |
+  ----- gamedir/
+```
+
+- Make sure you are in your virtualenv. Go to `evennia/docs/` and install the `requirements.txt` or run `make install` to do the same.
+
+
+## Building the docs.
+
+With your build environment set up as above, stand in the `evennia/docs` directory and run `make local`. This builds the documentation.
diff --git a/docs/checkenv.sh b/docs/checkenv.sh
index 42ceb6bc12..81af41b31c 100644
--- a/docs/checkenv.sh
+++ b/docs/checkenv.sh
@@ -1,11 +1,7 @@
 
 # check environment
 
-
-# if [ -n "$(git status --untracked-files=no --porcelain)" ]; then
-#   echo "There are uncommitted changes. Make sure to commit everything in your current branch first."
-#   exit 1
-# fi
+# common checks 
 
 if [ ! -d "$EVDIR" ]; then
 
@@ -22,3 +18,17 @@ if [ ! -d "$EVGAMEDIR" ]; then
 else
   echo "Evennia game dir correctly set to $EVGAMEDIR.";
 fi 
+
+if [ $# -ne 0 ]
+
+  # a multi-version build
+  
+  then 
+
+    if [ -n "$(git status --untracked-files=no --porcelain)" ]; then
+      echo "There are uncommitted changes. Make sure to commit everything in your current branch before doing a multiversion build."
+      exit 1
+    fi
+
+fi
+