Docs build process and docs cleaned up

Makefile

@@ -102,10 +102,10 @@ MANIFEST: MANIFEST.in $(SOURCE)
 
 # docs depend on the build as it partly use introspection.
 doc/html/genindex.html: $(PLATLIB) $(PURELIB) $(SOURCE_DOC)
-	PYTHONPATH=:$(BUILD_DIR):$$PYTHONPATH $(MAKE) -C doc html
+	$(MAKE) -C doc html
 
 doc/psycopg2.txt: $(PLATLIB) $(PURELIB) $(SOURCE_DOC)
-	PYTHONPATH=$(BUILD_DIR):$$PYTHONPATH $(MAKE) -C doc text
+	$(MAKE) -C doc text
 
 doc/docs.zip: doc/html/genindex.html
 	(cd doc/html && zip -r ../docs.zip *)

doc/Makefile

@@ -7,22 +7,27 @@ check: doctest
 # The environment is currently required to build the documentation.
 # It is not clean by 'make clean'
 
-help:
-	$(MAKE) SPHINXBUILD=$$(pwd)/env/bin/sphinx-build -C src $@
+PYTHON := python$(PYTHON_VERSION)
+PYTHON_VERSION ?= $(shell $(PYTHON) -c 'import sys; print ("%d.%d" % sys.version_info[:2])')
+
+SPHOPTS=PYTHONPATH=$$(pwd)/../build/lib.$(PYTHON_VERSION)/ SPHINXBUILD=$$(pwd)/env/bin/sphinx-build
 
 html:
-	$(MAKE) SPHINXBUILD=$$(pwd)/env/bin/sphinx-build -C src $@
+	$(MAKE) PYTHON=$(PYTHON) -C .. package
+	$(MAKE) $(SPHOPTS) -C src $@
 	cp -r src/_build/html .
 
 text:
-	$(MAKE) SPHINXBUILD=$$(pwd)/env/bin/sphinx-build -C src $@
+	$(MAKE) PYTHON=$(PYTHON) -C .. package
+	$(MAKE) $(SPHOPTS) -C src $@
 	cd src && tools/stitch_text.py index.rst _build/text > ../psycopg2.txt
 
 doctest:
-	$(MAKE) SPHINXBUILD=$$(pwd)/env/bin/sphinx-build -C src $@
+	$(MAKE) PYTHON=$(PYTHON) -C .. package
+	$(MAKE) $(SPHOPTS) -C src $@
 
 clean:
-	$(MAKE) SPHINXBUILD=$$(pwd)/env/bin/sphinx-build -C src $@
+	$(MAKE) $(SPHOPTS) -C src $@
 	rm -rf html psycopg2.txt
 
 env: requirements.txt

doc/README

@@ -1,42 +0,0 @@
-How to build psycopg documentation
-----------------------------------
-
-- Install Sphinx, maybe in a virtualenv. Tested with Sphinx 0.6.4::
-
-    ~$ virtualenv pd
-    New python executable in pd/bin/python
-    Installing setuptools............done.
-    ~$ cd pd
-    ~/pd$ source bin/activate
-    (pd)~/pd$ 
-
-- Install Sphinx in the env::
-
-    (pd)~/pd$ easy_install sphinx
-    Searching for sphinx
-    Reading http://pypi.python.org/simple/sphinx/
-    Reading http://sphinx.pocoo.org/
-    Best match: Sphinx 0.6.4
-    ...
-    Finished processing dependencies for sphinx
-
-- Build psycopg2 and ensure the package can be imported (it will be used for
-  reading the version number, autodocs etc.)::
-
-    (pd)~/pd/psycopg2$ python setup.py build
-    (pd)~/pd/psycopg2$ python setup.py install
-    running install
-    ...
-    creating ~/pd/lib/python2.6/site-packages/psycopg2
-    ...
-
-- Move to the ``doc`` dir and run ``make`` from there::
-
-    (pd)~/pd/psycopg2$ cd doc/
-    (pd)~/pd/psycopg2/doc$ make
-    Running Sphinx v0.6.4
-    ...
-
-You should have the rendered documentation in ``./html`` and the text file
-``psycopg2.txt`` now.
-

doc/README.rst

@@ -0,0 +1,26 @@
+How to build psycopg documentation
+----------------------------------
+
+Building the documentation usually requires building the library too for
+introspection, so you will need the same prerequisites_.  The only extra
+prerequisite is virtualenv_: the packages needed to build the docs will be
+installed when building the env.
+
+.. _prerequisites: http://initd.org/psycopg/docs/install.html#install-from-source
+.. _virtualenv: https://virtualenv.pypa.io/en/latest/
+
+Build the env once with::
+
+    make env
+
+Then you can build the documentation with::
+
+    make
+
+Or the single targets::
+
+    make html
+    make text
+
+You should find the rendered documentation in the ``html`` dir and the text
+file ``psycopg2.txt``.