Build autodocs for all our libraries.

Also updates doc build process and adds a README for it.

4 files changed, 66 insertions, 16 deletions

diff --git a/doc/source/Makefile b/doc/Makefile
index b2f74e85a..ed3172282 100644
--- a/doc/source/Makefile
+++ b/doc/Makefile
@@ -4,16 +4,19 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
+SPHINXSOURCE 	= source
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE)
 
 .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
 
+.DEFAULT_GOAL 	= html
+
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
@@ -29,34 +32,43 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm -rf nova.sqlite
+	-rm $(SPHINXSOURCE)/code.rst
+
+module_autodoc: generate_autodoc_index.sh
+	@echo "Generating module autodoc index."
+	./generate_autodoc_index.sh > $(SPHINXSOURCE)/code.rst
+
+source/code.rst: module_autodoc
+	@# pass
 
-html:
+html: source/code.rst
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml:
+dirhtml: source/code.rst
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-pickle:
+pickle: source/code.rst
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json:
+json: source/code.rst
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp:
+htmlhelp: source/code.rst
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
-qthelp:
+qthelp: source/code.rst
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -65,25 +77,25 @@ qthelp:
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc"
 
-latex:
+latex: source/code.rst
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
-changes:
+changes: source/code.rst
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck:
+linkcheck: source/code.rst
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
-doctest:
+doctest: source/code.rst
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/doc/README.rst b/doc/README.rst
new file mode 100644
index 000000000..565e8d5bf
--- /dev/null
+++ b/doc/README.rst
@@ -0,0 +1,33 @@
+=================
+Building the docs
+=================
+
+It is really easy. You'll need sphinx (the python one) and if you are using the virtualenv you'll need to install it in the virtualenv specifically so that it can load the nova modules.
+
+
+Use `make`
+==========
+
+Just type make::
+
+  % make
+
+Look in the Makefile for more targets.
+
+
+Manually
+========
+
+  1. Generate the code.rst file so that Sphinx will pull in our docstrings::
+     
+      % ./generate_autodoc_index.sh > source/code.rst
+
+  2. Run `sphinx_build`::
+
+      % sphinx-build -b html source build/html
+
+
+The docs have been built
+========================
+
+Check out the `build` directory to find them. Yay!
diff --git a/doc/find_undocumented_classes.sh b/doc/find_modules.sh
index 845e0b5e0..81a006e3b 100755..100644
--- a/doc/find_undocumented_classes.sh
+++ b/doc/find_modules.sh
@@ -8,13 +8,10 @@ for x in `find ${NOVA_DIR} -name '*.py'`; do
     if [ `basename ${x} .py` == "__init__" ] ; then
         continue
     fi
-    relative=nova.`echo ${x} | sed -e 's$^'${NOVA_DIR}'$$' -e 's/.py$//' -e 's$/$.$g'`
+    relative=nova`echo ${x} | sed -e 's$^'${NOVA_DIR}'$$' -e 's/.py$//' -e 's$/$.$g'`
     modules="${modules} ${relative}"
 done
 
 for mod in ${modules} ; do
-    op=`grep ${mod} ${DOCS_DIR}/*.rst`
-    if [ -z "${op}" ] ; then
         echo ${mod}
-    fi
 done
diff --git a/doc/generate_autodoc_index.sh b/doc/generate_autodoc_index.sh
new file mode 100644
index 000000000..069b053a1
--- /dev/null
+++ b/doc/generate_autodoc_index.sh
@@ -0,0 +1,8 @@
+#!/bin/sh
+
+for x in `./find_modules.sh`;
+do
+  echo ".. automodule:: ${x}"
+  echo "  :members:"
+done
+