Restructuring the documentation to make beginner and advanced examples more obvious in TOC, adding details about GridSearch usage.

Author: Team AiGameDev.com

docs/guide_advanced.rst

@@ -0,0 +1,70 @@
+Advanced Usage
+==============
+
+The examples in this section help you get more out of ``scikit-neuralnetwork`` via integration or configuration of the other libraries it works with, such as Theano or scikit-learn.
+
+
+GPU Backend
+-----------
+
+To setup the library to use your GPU or CPU explicitly in 32-bit or 64-bit mode, you can use the ``backend`` pseudo-module.  It's a syntactic helper to setup ``THEANO_FLAGS`` in a Pythonic way, for example:
+
+.. code:: python
+
+    # Use the GPU in 32-bit mode, falling back otherwise.
+    from sknn.backend import gpu32
+    
+    # Use the CPU in 64-bit mode.
+    from sknn.backend import cpu64
+    
+
+WARNING: This will only work if your program has not yet imported the ``theano`` module, due to the way the library is designed.  If ``THEANO_FLAGS`` are set on the command-line, they are not overwridden.
+
+
+
+Pipeline
+--------
+
+Typically, neural networks perform better when their inputs have been normalized or standardized.  Using a scikit-learn's `pipeline <http://scikit-learn.org/stable/modules/generated/sklearn.pipeline.Pipeline.html>`_ support is an obvious choice to do this.
+
+Here's how to setup such a pipeline with a multi-layer perceptron as a classifier:
+
+.. code:: python
+
+    from sknn.mlp improt Classifier, Layer
+
+    from sklearn.pipeline import Pipeline
+    from sklearn.preprocessing import MinMaxScaler
+
+    pipeline = Pipeline([
+            ('min/max scaler', MinMaxScaler(feature_range=(0.0, 1.0))),
+            ('neural network', Classifier(layers=[Layer("Softmax")], n_iter=25))])
+    pipeline.fit(X_train, y_train)
+
+You can then use the pipeline as you would the neural network, or any other standard API from scikit-learn.
+
+
+
+Grid Search
+-----------
+
+In scikit-learn, you can use a ``GridSearchCV`` to optimize your neural network's parameters automatically, both the top-level parameters and the parameters within the layers.  For example, assuming you have your MLP constructed as in the :ref:`Regression` example in the local variable called ``nn``, the layers are named automatically so you can refer to them as follows:
+
+    * ``hidden0``
+    * ``hidden1``
+    * ...
+    * ``output2``
+     
+Keep in mind you can manually specify the ``name`` of any ``Layer`` in the constructor if you don't want the automatically assigned name.  Then, you can use sklearn's hierarchical parameters to perform a grid search over those nested parameters too: 
+
+.. code:: python
+
+    from sklearn.grid_search import GridSearchCV
+
+    gs = GridSearchCV(nn, param_grid={
+        learning_rate: [0.05, 0.01, 0.005, 0.001],
+        'hidden0__units': [4, 8, 12],
+        'hidden0__type': ["Rectifier", "Sigmoid", "Tanh"]})
+    gs.fit(a_in, a_out)
+    
+This will search through the listed ``learning_rate`` values, the number of hidden units and the activation type for that layer too, and find the best combination of parameters.

docs/guide.rst renamed to docs/guide_beginners.rst

@@ -1,5 +1,5 @@
-User Guide
-==========
+Simple Examples
+===============
 
 Regression
 ----------
@@ -106,42 +106,3 @@ Working with images as inputs in 2D (as greyscale) or 3D (as RGB) images stored
     nn.fit(X_train, y_train)
 
 The neural network here is trained with eight kernels of shared weights in a ``3x3`` matrix, each outputting to its own channel.  The rest of the code remains the same, but see the :class:`sknn.mlp.Layer` documentation for supported convolution layer types and parameters.
-
-
-Pipeline
---------
-
-Typically, neural networks perform better when their inputs have been normalized or standardized.  Using a scikit-learn's `pipeline <http://scikit-learn.org/stable/modules/generated/sklearn.pipeline.Pipeline.html>`_ support is an obvious choice to do this.
-
-Here's how to setup such a pipeline with a multi-layer perceptron as a classifier:
-
-.. code:: python
-
-    from sknn.mlp improt Classifier, Layer
-
-    from sklearn.pipeline import Pipeline
-    from sklearn.preprocessing import MinMaxScaler
-
-    pipeline = Pipeline([
-            ('min/max scaler', MinMaxScaler(feature_range=(0.0, 1.0))),
-            ('neural network', Classifier(layers=[Layer("Softmax")], n_iter=25))])
-    pipeline.fit(X_train, y_train)
-
-You can thes use the pipeline as you would the neural network, or any other standard API from scikit-learn.
-
-
-GPU Backend
------------
-
-To setup the library to use your GPU or CPU explicitly in 32-bit or 64-bit mode, you can use the ``backend`` pseudo-module.  It's a syntactic helper to setup ``THEANO_FLAGS`` in a Pythonic way, for example:
-
-.. code:: python
-
-    # Use the GPU in 32-bit mode, falling back otherwise.
-    from sknn.backend import gpu32
-    
-    # Use the CPU in 64-bit mode.
-    from sknn.backend import cpu64
-    
-
-WARNING: This will only work if your program has not yet imported the ``theano`` module, due to the way the library is designed.  If ``THEANO_FLAGS`` are set on the command-line, they are not overwridden.

docs/guide_start.rst

@@ -0,0 +1,29 @@
+Installation
+============
+
+Downloading Package
+-------------------
+
+To download and setup the last officially released package, you can do so from PYPI directly::
+
+    > pip install scikit-neuralnetwork
+
+This contains its own packaged version of ``pylearn2`` from the date of the release (and tag) but will use any globally installed version if available.
+
+If you want to install the very latest from source, please visit the `Project Page <https://github.com/aigamedev/scikit-neuralnetwork>`_ on GitHub for details.
+
+
+Running Tests
+-------------
+
+We encourage you to launch the tests to check everything is working using the following commands::
+
+    > pip install nose
+    > nosetests -v sknn
+
+Use the additional command-line parameters in the test runner ``--processes=8`` and ``--process-timeout=60`` to speed things up on powerful machines.  The result should look as follows in your terminal.
+
+.. image:: console_tests.png
+
+We strive to maintain 100% test coverage for all code-paths, to ensure that rapid changes in the underlying ``pylearn2`` library are caught automatically.
+

docs/index.rst

@@ -3,10 +3,13 @@ Welcome to sknn's documentation!
 
 Deep neural network implementation without the learning cliff! This library implements multi-layer perceptrons as a wrapper for the powerful ``pylearn2`` library that's compatible with ``scikit-learn`` for a more user-friendly and Pythonic interface.
 
-|Build Status| |Documentation Status| |Code Coverage| |License Type| |Source Code|
+|Build Status| |Code Coverage| |License Type| |Source Code|
 
 ----
 
+.. image:: plot_activation.png
+
+
 Module Reference
 ----------------
 
@@ -16,46 +19,15 @@ Module Reference
     mlp
 
 
-Installation
-------------
-
-You'll need to first install some dependencies manually.  Unfortunately, ``pylearn2`` isn't yet installable via PyPI and recommends an editable (``pip -e``) installation::
-
-    > pip install numpy scipy theano
-    > pip install -e git+https://github.com/lisa-lab/pylearn2.git#egg=Package
-
-Once that's done, you can grab this repository and install from ``setup.py`` in the exact same way::
-
-    > git clone https://github.com/aigamedev/scikit-neuralnetwork.git
-    > cd scikit-neuralnetwork; python setup.py develop
-
-Then, you can run the samples and benchmarks available in the ``examples/`` folder.
-
-
-Running Tests
--------------
-
-We encourage you to launch the tests to check everything is working using the following commands::
-
-    > pip install nose
-    > nosetests -v sknn
-
-Use the additional command-line parameters in the test runner ``--processes=8`` and ``--process-timeout=60`` to speed things up on powerful machines.  The result should look as follows in your terminal.
-
-.. image:: console_tests.png
-
-We strive to maintain 100% test coverage for all code-paths, to ensure that rapid changes in the underlying ``pylearn2`` library are caught automatically.
-
-
-Getting Started
----------------
+User Guide
+----------
 
 .. toctree::
     :maxdepth: 2
 
-    guide
-
-.. image:: plot_activation.png
+    guide_start
+    guide_beginners
+    guide_advanced
 
 
 Indices & Search
@@ -67,14 +39,11 @@ Indices & Search
 
 ----
 
-|Build Status| |Documentation Status| |Code Coverage| |License Type| |Source Code|
+|Build Status| |Code Coverage| |License Type| |Source Code|
 
 .. |Build Status| image:: https://travis-ci.org/aigamedev/scikit-neuralnetwork.svg?branch=master
    :target: https://travis-ci.org/aigamedev/scikit-neuralnetwork
 
-.. |Documentation Status| image:: https://readthedocs.org/projects/scikit-neuralnetwork/badge/?version=latest
-    :target: http://scikit-neuralnetwork.readthedocs.org/
-
 .. |Code Coverage| image:: https://coveralls.io/repos/aigamedev/scikit-neuralnetwork/badge.svg?branch=master
     :target: https://coveralls.io/r/aigamedev/scikit-neuralnetwork?branch=master
 

docs/pypi.rst

@@ -25,16 +25,16 @@ Thanks to the underlying ``pylearn2`` implementation, this library supports the
 If a feature you need is missing, consider opening a `GitHub Issue <https://github.com/aigamedev/scikit-neuralnetwork/issues>`_ with a detailed explanation about the use case and we'll see what we can do.
 
 
-Installation & Testing
-----------------------
+Installation
+------------
 
 To download and setup the latest official release, you can do so from PYPI directly::
 
     > pip install scikit-neuralnetwork
 
 This contains its own packaged version of ``pylearn2`` from the date of the release (and tag) but will use any globally installed version if available.
 
-Then, you can run the samples and benchmarks available in the ``examples/`` folder.
+Then, you can run the tests using ``nosetests -v sknn``, and other samples or benchmarks are available in the ``examples/`` folder.
 
 
 Getting Started