Add API generation and fix documentation build.

doc/Makefile

@@ -31,7 +31,12 @@ help:
 clean:
 	-rm -rf build/*
 
-html:
+api:
+	mkdir -p source/api
+	python tools/build_modref_templates.py
+	@echo "Build API docs finished."
+
+html: api
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."

doc/source/_templates/index.html

@@ -0,0 +1,79 @@
+{% extends "layout.html" %}
+{% set title = 'Home' %}
+{% block body %}
+
+   <h1>{{ docstitle }}</h1>
+   <p>This is the official documentation for {{project}} {{release}}.</p>
+
+   <h2>Sections</h2>
+   <table class="contentstable" align="center">
+      <tr valign="top"><td width="50%">
+      <p class="biglink">
+         <a class="biglink" href="{{ pathto('overview') }}">
+            Overview</a><br>
+         <span class="linkdescr">
+            Get started with {{project}}.
+         </span></p>
+
+      <p class="biglink">
+         <a class="biglink" href="{{ pathto('install') }}">
+            Installation Steps</a><br>
+         <span class="linkdescr">
+            Quickly install {{project}} to your system.
+         </span></p>
+
+      <p class="biglink">
+         <a class="biglink" href="{{ pathto('api/api') }}">
+            API (Developer's) Reference</a><br>
+         <span class="linkdescr">
+            Overview of what's in {{project}} and how to use it.
+         </span></p>
+
+   </td><td width="50%">
+
+      <p class="biglink">
+         <a class="biglink" href="{{ pathto('changelog') }}">
+            What's new in {{project}}?</a><br>
+         <span class="linkdescr">
+            Changes made in each {{project}} release.
+         </span></p>
+
+      <p class="biglink">
+         <a class="biglink" href="{{ pathto('license') }}">
+            License Info</a><br>
+         <span class="linkdescr">
+            How you can use this software and the source code.
+         </span></p>
+
+   </td></tr></table>
+
+   <h2>Indices and Tables</h2>
+
+   <table class="contentstable" align="center">
+      <tr valign="top"><td width="50%">
+      <p class="biglink">
+         <a class="biglink" href="{{ pathto('contents') }}">
+            Table of Contents</a><br>
+         <span class="linkdescr">
+            Lists all sections and subsections.
+         </span></p>
+
+      <p class="biglink">
+         <a class="biglink" href="{{ pathto('search') }}">
+            Search Page</a><br>
+         <span class="linkdescr">
+            Search this documentation.
+         </span></p>
+
+      </td><td width="50%">
+
+      <p class="biglink">
+         <a class="biglink" href="{{ pathto('genindex') }}">
+            Index</a><br>
+         <span class="linkdescr">
+            All functions, classes, terms.
+         </span></p>
+
+    </td></tr></table>
+
+{% endblock %}

doc/source/conf.py

@@ -18,11 +18,14 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.append(os.path.abspath('.'))
 
+curpath = os.path.dirname(__file__)
+sys.path.append(os.path.join(curpath, '../ext'))
+
 # -- General configuration -----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -34,7 +37,7 @@
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'contents'
 
 # General information about the project.
 project = u'scikits.image'
@@ -92,6 +95,7 @@
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
 html_theme = 'default'
+#html_style = 'scipy.css'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -135,7 +139,7 @@
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-#html_additional_pages = {}
+html_additional_pages = {'index': 'index.html'}
 
 # If false, no module index is generated.
 #html_use_modindex = True
@@ -178,7 +182,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'scikitsimage.tex', u'scikits.image Documentation',
+  ('contents', 'scikitsimage.tex', u'scikits.image Documentation',
    u'SciPy Developers', 'manual'),
 ]
 

doc/source/contents.txt

@@ -0,0 +1,4 @@
+.. toctree::
+
+   /api/api
+

doc/source/index.txt

@@ -1,20 +1,3 @@
-.. scikits.image documentation master file, created by
-   sphinx-quickstart on Sat Aug 22 13:00:30 2009.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to scikits.image's documentation!
-=========================================
-
-Contents:
-
 .. toctree::
-   :maxdepth: 2
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
 
+   /api/api

doc/tools/LICENSE.txt

@@ -0,0 +1,7 @@
+These files were obtained from
+
+http://groups.google.com/group/sphinx-dev/browse_thread/thread/595ef2eff60084c5/
+
+and were released under a BSD/MIT license by Fernando Perez, Matthew Brett and
+the PyMVPA guys.
+