Fix documentation build

This builds both asyncio and Twisted documentation, all inside a virtualenv.

I took the "sphinx-build" commands out of SCons because I couldn't get them
to work from there properly within a virtualenv -- perhaps I'm just missing
something easy here though.

doc/Makefile

@@ -11,11 +11,19 @@ all:
 	@echo "  doctest           : run doctests"
 	@echo ""
 
-build:
-	scons
+# need a distribution package for SCons, like "apt-get install scons"
+venv:
+	virtualenv --system-site-packages --python=python2 venv
 
-build_no_network:
-	scons --no_network
+# the "python `which scons`" hacks are because I can't get scons
+# installed in a virtualenv, and its #! hard-codes to system python
+build: install_deps
+	./venv/bin/python `which scons`
+	./venv/bin/sphinx-build -A cstatic="//tavendo-common-static.s3-eu-west-1.amazonaws.com" -b html . _build
+
+build_no_network: install_deps
+	./venv/bin/python `which scons` --no_network
+	./venv/bin/sphinx-build -A no_network=1 -D no_network=1 -A cstatic="http://127.0.0.1:8888" -b html . _build
 
 test: build
 	python serve.py --root ./_build --silence
@@ -29,6 +37,7 @@ clean:
 	rm -rf _static/img/gen
 	rm -rf _test
 	rm -rf _spelling
+	rm -rf ./venv
 
 publish: clean build
 	scons publish
@@ -68,15 +77,15 @@ copy_wordlist:
 
 copy: copy_makefile copy_gitignore copy_serve
 
-install_deps:
-	pip install -U scour
-	pip install -U taschenmesser
-	#pip install -U scons
-	pip install -U sphinx
-	pip install -U sphinx-bootstrap-theme
-	pip install -U pyenchant
-	pip install -U sphinxcontrib-spelling
-	pip install -U repoze.sphinx.autointerface
+install_deps: venv
+	./venv/bin/pip install -U scour
+	./venv/bin/pip install -U taschenmesser
+	./venv/bin/pip install -U sphinx
+	./venv/bin/pip install -U sphinx-bootstrap-theme
+	./venv/bin/pip install -U pyenchant
+	./venv/bin/pip install -U sphinxcontrib-spelling
+	./venv/bin/pip install -U repoze.sphinx.autointerface
+	./venv/bin/pip install -e ../[twisted,asyncio]
 
 spelling:
 	PYTHONPATH=../autobahn sphinx-build -b spelling . _spelling

doc/README.md

@@ -10,6 +10,8 @@ You will need to have Python and [SCons](http://www.scons.org/) installed. To in
 make install_deps
 ```
 
+**Note:** If you want to use this in a virtualenv, you'll have to install the SCons package for your distribution and use ``virtualenv --system-site-packages`` to build the venv. Then, activate it and install dependencies as above. To run SCons you'll have to do ``python `which scons` `` so that it uses the interpreter from your virtualenv.
+
 Then, to get help on available build targets, just type
 
 ```sh

doc/SConstruct

@@ -73,35 +73,15 @@ env = Environment(tools = ['default', 'taschenmesser'],
 ## Process SVGs
 ##
 imgs = env.process_svg(SVG_FILES, IMG_SOURCE_DIR, IMG_GEN_DIR)
-
 Alias("img", imgs)
-
-
-## Sphinx Build
-##
-if GetOption('no_network'):
-   print("Building for no network")
-   docs = env.Command(DOCSDIR, [], 'sphinx-build -A no_network=1 -D no_network=1 -A cstatic="{}" -b html . $TARGET'.format(CSTATIC_LOCAL))
-else:
-   docs = env.Command(DOCSDIR, [], 'sphinx-build -A cstatic="{}" -b html . $TARGET'.format(CSTATIC))
-
-
-# sphinx-build -b spelling . _spelling
-
-env.AlwaysBuild(docs)
-Clean(docs, DOCSDIR)
-Alias("doc", docs)
-
-Default([imgs, docs])
+Default("img")
 
 
 ## Upload to Amazon S3
 ##
-uploaded = env.s3_dir_uploader(UPLOADED, DOCSDIR, BUCKET, BUCKET_PREFIX)
-
-Depends(uploaded, docs)
-Depends(uploaded, imgs)
-
-Clean(uploaded, UPLOADED)
-
-Alias("publish", uploaded)
+if hasattr(env, 's3_dir_uploader'):
+    uploaded = env.s3_dir_uploader(UPLOADED, DOCSDIR, BUCKET, BUCKET_PREFIX)
+    # Depends(uploaded, docs)
+    # Depends(uploaded, imgs)
+    Clean(uploaded, UPLOADED)
+    Alias("publish", uploaded)