doc: build improvements

Sphinx has difficulties in finding modules on given path.
Added a script that installs all required python eggs in temporary
directory and uses that for generating API documentation.

3 files changed, 40 insertions, 5 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 8054789..91bd7f3 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -9,7 +9,7 @@ BUILDDIR         ?= _build
 PROJECTNAME       = OpenLMIScripts
 COMMANDS_PATH    ?= ../commands
 INCLUDE_COMMANDS ?= 0
-COMMANDS         ?= service software storage
+COMMANDS         ?= logicalfile service software storage
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -18,7 +18,9 @@ ALLSPHINXOPTS   = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext commands.rst
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp \
+    devhelp epub latex latexpdf text man changes linkcheck doctest gettext \
+    commands.rst
 
 all: html epub latexpdf
 
@@ -63,7 +65,6 @@ ifneq ($(INCLUDE_COMMANDS), 0)
 	for cmd in $(COMMANDS); do \
 	    printf "    commands/$$cmd\n" >> $@; \
 	    ln -s ../$(COMMANDS_PATH)/$${cmd}/doc commands/$${cmd}_docdir; \
-	    make -C commands/$${cmd}_docdir html; \
 	    title="$${cmd^} library"; \
 	    length=`echo "$$title" | wc -c`; \
 	    ( \
@@ -117,7 +118,7 @@ figures:
 
 
 html: figures api.rst commands.rst
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	./build-with-sphinx.sh "$(COMMANDS)" -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
diff --git a/doc/build-with-sphinx.sh b/doc/build-with-sphinx.sh
new file mode 100755
index 0000000..e1a08d2
--- /dev/null
+++ b/doc/build-with-sphinx.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+# This script creates a temporary python workspace directory, where the
+# openlmi-scripts and all specified commands are installed in order for
+# sphinx-build to successfuly find them and generate devel documentation out of
+# them.
+#
+# There are several environment variables affecting the execution:
+#   * SPHINXBUILD
+#           sphinx binary generating the documentation
+#   * INCLUDE_COMMANDS
+#           whether the command should be included in generated documentation
+#   * COMMANDS
+#           list of subcommands to include
+
+SPHINXBUILD=${SPHINXBUILD:-sphinx-build}
+INCLUDE_COMMANDS=${INCLUDE_COMMANDS:-1}
+tmp=`mktemp -d`
+pushd ..
+export PYTHONPATH=$tmp
+python setup.py develop --install-dir=$tmp || exit 1
+if [ "$INCLUDE_COMMANDS" == 1 ]; then
+    pushd commands
+    COMMANDS="$1"
+    for cmd in ${COMMANDS}; do
+        pushd $cmd
+        python setup.py develop --install-dir=$tmp || exit 1
+        popd
+    done
+    popd
+fi
+popd  # ..
+shift
+${SPHINXBUILD} $@ || exit 1
+rm -rf $tmp
diff --git a/doc/conf.py b/doc/conf.py
index 193b861..fa61860 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -16,7 +16,7 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('../lmi'))
+sys.path.insert(0, os.path.abspath('..'))
 
 if os.environ.get('INCLUDE_COMMANDS', '0').lower() in {'1', 'true', 'yes'}:
     commands_path = os.environ.get('COMMANDS_PATH', '../commands')