improving docs

.gitignore

@@ -1,2 +1,6 @@
 *.pyc
 *~
+*.DS_Store
+_build/
+auto_examples/
+gen_api/

doc/Makefile

@@ -177,3 +177,6 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+show:
+	@python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/_build/html/index.html')"

doc/_templates/class.rst

@@ -0,0 +1,13 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :special-members: __contains__,__getitem__,__iter__,__len__,__add__,__sub__,__mul__,__div__,__neg__,__hash__
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div style='clear:both'></div>

doc/_templates/function.rst

@@ -0,0 +1,12 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div style='clear:both'></div>

doc/api.rst

@@ -0,0 +1,26 @@
+API
+===
+
+
+Classes
+-------
+
+.. currentmodule:: shablona
+
+.. autosummary::
+   :template: class.rst
+   :toctree: gen_api
+
+   Model
+
+
+Functions
+---------
+
+.. autosummary::
+   :template: function.rst
+   :toctree: gen_api
+
+   transform_data
+   cumgauss
+   opt_err_func

doc/conf.py

@@ -8,7 +8,7 @@
 # containing dir.
 #
 # Note that not all possible configuration values are present in this
-# autogenerated file.
+# autogene`rated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
@@ -28,16 +28,6 @@
 
 currentdir = os.path.abspath(os.path.dirname(__file__))
 sys.path.append(os.path.join(currentdir, 'tools'))
-import buildmodref
-
-# autogenerate api documentation
-# (see https://github.com/rtfd/readthedocs.org/issues/1139)
-def generateapidoc(_):
-    output_path = os.path.join(currentdir, 'reference')
-    buildmodref.writeapi(project, output_path, source_version, True)
-
-def setup(app):
-    app.connect('builder-inited', generateapidoc)
 
 # 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
@@ -47,7 +37,7 @@ def setup(app):
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.0' # numpydoc requires sphinc >= 1.0
+needs_sphinx = '1.0'  # numpydoc requires sphinc >= 1.0
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -84,8 +74,16 @@ def setup(app):
     # path to your examples scripts
     'examples_dirs': '../examples',
     # path where to save gallery generated examples
-    'gallery_dirs': 'auto_examples'}
+    'gallery_dirs': 'auto_examples',
+    # To auto-generate example sections in the API
+    'doc_module': ('shablona',),
+    # Auto-generated mini-galleries go here
+    'backreferences_dir': 'gen_api'
+}
 
+# Automatically generate stub pages for API
+autosummary_generate = True
+autodoc_default_flags = ['members', 'inherited-members']
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -139,7 +137,7 @@ def setup(app):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinxdoc'
+html_theme = 'alabaster'
 
 # 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
@@ -158,7 +156,7 @@ def setup(app):
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '_static/logo.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -184,7 +182,7 @@ def setup(app):
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {'**': ['localtoc.html', 'searchbox.html']}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

doc/index.rst

@@ -20,12 +20,4 @@ Contents:
 
    theory
    auto_examples/index
-   reference/index
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+   api