Merge pull request #2658 from abergeron/doc

Doc update

Merge pull request #2658 from abergeron/doc
3fcaaf14 · Pascal Lamblin · 0838ae4d · 71410fd9 · 3fcaaf14 · 3fcaaf14
--- a/doc/dev_start_guide.txt
+++ b/doc/dev_start_guide.txt
@@ -379,32 +379,41 @@ Then in your ``~/.emacs`` file, add this:
 Unit tests
 ----------

-Before submitting a pull request, you should run the unit test suite,
-and make sure that your changes did not create any new Error or Failure.
-You can consult `theano-buildbot`_ for the result of a recent run
-of the test suite with various options.
+When you submit a pull request, your changes will automatically be
+tested via Travis-CI. This will post the results of the tests with a
+little icon next to your commit. A yellow circle means the tests are
+running.  A red X means the tests failed and a green circle means the
+tests passed.
+
+Just because the tests run automatically does not mean you shouldn't
+run them yourself to make sure everything is all right.  You can run
+only the portion you are modifying to go faster and have travis to
+make sure there are no global impacts.
+
+Also, if you are changing GPU code, travis doesn't test that, because
+there are no GPUs on the test nodes.

 To run the test suite with the default options, you can follow the
 instructions of :ref:`testing_installation`.

-Each night we execute all the unit tests automatically, with different
-sets of options.  The result is sent by email to the `theano-buildbot`_
+Each night we execute all the unit tests automatically, with several
+sets of options. The result is sent by email to the `theano-buildbot`_
 mailing list.

 For more detail, see :ref:`metadocumentation_nightly_build`.

-To run all the tests with the same configuration as the buildbot, run this script:
+To run all the tests with the same configuration as the buildbot, run
+this script:

 .. code-block:: bash

   theano/misc/do_nightly_build

-This function accepts arguments that it forward to nosetests. You can
+This script accepts arguments that it forwards to nosetests. You can
 run only some tests or enable pdb by giving the equivalent nosetests
 parameters.


-
 More Advanced Git Usage
 =======================


--- a/doc/index.txt
+++ b/doc/index.txt
@@ -81,8 +81,8 @@ installation and configuration, see :ref:`installing Theano <install>`.

     <a href="https://crate.io/packages/Theano/"><img src="https://pypip.in/d/Theano/badge.png" alt="Number of PyPI downloads" /></a>&nbsp;

-  .. _available on PyPI: http://pypi.python.org/pypi/Theano
-  .. _Related Projects: https://github.com/Theano/Theano/wiki/Related-projects
+.. _available on PyPI: http://pypi.python.org/pypi/Theano
+.. _Related Projects: https://github.com/Theano/Theano/wiki/Related-projects

 Citing Theano
 ==============
@@ -95,7 +95,7 @@ required) to cite the following two papers:
  `"Theano: new features and speed improvements"
  <http://arxiv.org/pdf/1211.5590.pdf>`_.
  NIPS 2012 deep learning workshop. (`BibTex
-  <http://www.iro.umontreal.ca/~lisa/publications2/index.php/export/publication/551/bibtex>`_)
+  <http://www.iro.umontreal.ca/~lisa/publications2/index.php/export/publication/551/bibtex>`__)

 * J. Bergstra, O. Breuleux, F. Bastien, P. Lamblin, R.
  Pascanu, G. Desjardins, J. Turian, D. Warde-Farley and Y.
@@ -103,7 +103,7 @@ required) to cite the following two papers:
  <http://www.iro.umontreal.ca/~lisa/pointeurs/theano_scipy2010.pdf>`_.
  *Proceedings of the Python for Scientific Computing Conference (SciPy)
  2010. June 30 - July 3, Austin, TX* (`BibTeX
-  <http://www.iro.umontreal.ca/~lisa/publications2/index.php/export/publication/461/bibtex>`_)
+  <http://www.iro.umontreal.ca/~lisa/publications2/index.php/export/publication/461/bibtex>`__)

 Theano is primarily developed by academics, and so citations matter a lot to
 us. As an added benefit, you increase Theano's exposure and potential user
@@ -183,7 +183,6 @@ Community
   glossary
   links
   internal/index
-   examples/index
   proposals/index
   acknowledgement
   LICENSE

--- a/doc/install.txt
+++ b/doc/install.txt
@@ -507,81 +507,60 @@ Note that:
 Once your setup is complete, head to :ref:`using_gpu` to find how to verify
 everything is working properly.

-.. note::
-    There is a compatibility issue affecting some Ubuntu 9.10 users, and probably anyone using
-    CUDA 2.3 with gcc-4.4.  Symptom: errors about "__sync_fetch_and_add" being undefined.
-    **Solution 1:** make gcc-4.3 the default gcc
-    (http://pascalg.wordpress.com/2010/01/14/cuda-on-ubuntu-9-10linux-mint-helena/)
-    **Solution 2:** make another gcc (e.g. gcc-4.3) the default just for nvcc.
-    Do this by making a directory (e.g. ``$HOME/.theano/nvcc-bindir``) and
-    installing two symlinks in it: one called gcc pointing to gcc-4.3 (or lower) and one called
-    g++ pointing to g++-4.3 (or lower).  Then add
-    ``compiler_bindir = /path/to/nvcc-bindir`` to the ``[nvcc]`` section of your ``.theanorc``
-    (`libdoc_config`).
-
-
 .. _Graphviz: http://www.graphviz.org/Download_windows.php

-MacOS
-----
+Mac OS
+------

-There are various ways to install Theano dependencies on a Mac.
-Here we describe the process in detail with EPD, Anaconda or with MacPorts, but if you did
-it differently and it worked, please let us know the details on the
-`theano-users`_ mailing-list, so that we can add alternate instructions
-here.
+There are various ways to install Theano dependencies on a Mac. Here
+we describe the process in detail with Canopy, Anaconda, Homebrew or
+MacPorts but if you did it differently and it worked, please let us
+know the details on the `theano-users`_ mailing-list, so that we can
+add alternate instructions here.


-In academia: Enthought Python Distribution (EPD)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In academia: Enthought Canopy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 If you are working in academia, the easiest way to install most of the
 dependencies is to install
-`Enthought Python Distribution (EPD) <http://enthought.com/products/epd.php>`_.
-If you are affiliated with a university (as student or employee), you can
-download the installer for free.
-
-EPD installation includes in particular Python (and the development headers),
-NumPy, SciPy, nose, sphinx, easy_install, pydot (but *not* `Graphviz`_, which is
-necessary for it to work) and the MKL implementation of blas. The Mac OS and
-Linux version do not include g++.
+`Canopy <http://enthought.com/products/canopy/>`_.
+If you are affiliated with a university (as student or employee), you
+can download the installer for free.

-pip is not included in EPD. After the installation of EPD,
-you can simply install it with::
+The Canopy installation includes in particular Python (and the
+development headers), NumPy, SciPy, nose, sphinx, pip, pydot
+(but *not* `Graphviz`_, which is necessary for it to work) and the MKL
+implementation of blas.

-    .. code-block:: bash
+To install the latest Theano release execute this in a terminal:

-        $ sudo easy_install pip
-
-Then in a terminal execute this command to install the latest Theano release:
-
-    .. code-block:: bash
+.. code-block:: bash

-        $ sudo pip install Theano
+    $ pip install Theano

-If you want the bleeding edge version, `download
-and install git <http://git-scm.com/downloads>`_. Then in a
-terminal excute this command:
+If you want the bleeding edge version execute this command instead:

 .. code-block:: bash

-    $ sudo pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git
+    $ pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git

 See the section `install_bleeding_edge`_ for more
 information on the bleeding edge version.

-Then you must install g++. You can do this by installing XCode. See the first bullet in the :ref:`macports` section.
+Then you must install the compiler. See :ref:`compiler_osx` below.

 .. note::

-   If you use the trunk or version 0.6 or later of Theano, we try to
-   automatically link with the EPD blas version.  Due to Mac OS
-   peculiarities, we need a user intervention to do it.  We detect
-   if the user did the modification and if not, we tell him how to do
-   it.
+   If you use version 0.6 or later of Theano, we try to automatically
+   link with the Canopy blas version.  Due to Mac OS peculiarities,
+   this requires user intervention.  We detect if the manipulation was
+   done or not and give an error message explaining what to do in case
+   it hasn't been done.
+

-Anaconda 1.5
-~~~~~~~~~~~~
+Anaconda
+~~~~~~~~

 An easy way to install most of the dependencies is to install
 `Anaconda <http://continuum.io/downloads.html>`_. There is a free
@@ -590,45 +569,92 @@ Optimizations`` product (free for academic, ~30$ otherwise) Theano
 will also be optimized as we will reuse the faster BLAS version
 automatically.

-Anaconda installation includes in particular Python (and the development headers),
-NumPy, SciPy, nose, sphinx, pip, and a acceptable BLAS version. The Mac OS and
-Linux version do not include g++.
+The Anaconda installation includes in particular Python (and the
+development headers), NumPy, SciPy, nose, sphinx, pip, and a
+acceptable BLAS version.

 After installing Anaconda, in a terminal execute this command to
 install the latest Theano release:

-    .. code-block:: bash
+.. code-block:: bash

-        $ pip install Theano
+    $ pip install Theano

 To install the missing Theano optional dependency (pydot):

-    .. code-block:: bash
+.. code-block:: bash

-        $ conda install pydot
+    $ conda install pydot

-If you want the bleeding edge version, `download
-and install git <http://git-scm.com/downloads>`_. Then in a
-terminal execute this command:
+If you want the bleeding edge version instead execute this command:

 .. code-block:: bash

-    $ sudo pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git
+    $ pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git

 See the section `install_bleeding_edge`_ for more
 information on the bleeding edge version.

-Then you must install g++. You can do this by installing XCode. See the first bullet in the :ref:`macports` section.
+Then you must install the compiler. See :ref:`compiler_osx` below.

 .. note::

-   If you use the trunk or a version after 0.6rc3 of Theano, we try to
-   automatically link with the python library.  Due to Mac OS
-   peculiarities, we need a user intervention to do it.  We detect
-   if the user did the modification and if not, we tell him how to do
-   it.
+   If you use version 0.6 or later of Theano, we try to automatically
+   link with the python library.  Due to Mac OS peculiarities, this
+   requires user intervention.  We detect if the user did the
+   modification and if not, we tell him how to do it.
+
+.. _compiler_osx:
+
+Installing the compiler
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Theano officially supports only clang on OS X.  This can be installed
+by getting XCode from the App Store and running it once to install the
+command-line tools.
+
+If you still want to use g++ you can do so by setting its full path in
+the theano config flag `gxx`.  Note that any bug reports on Mac using
+g++ will be ignored unless it can be reproduced with clang.
+
+
+Homebrew
+~~~~~~~~
+
+Install python with homebrew:
+
+.. code-block:: bash
+
+    $ brew install python # or python3 if you prefer
+
+This will install pip.  Then use pip to install numpy, scipy:
+
+.. code-block:: bash
+
+    $ pip install numpy scipy
+
+If you want to use openblas instead of Accelerate, you have to install
+numpy and scipy with hombrew:
+
+.. code-block:: bash
+
+    $ brew tap homebrew/python
+    $ brew install numpy --with-openblas
+    $ brew install scipy --with-openblas
+
+
+Then install theano as usual:
+
+.. code-block:: bash
+
+    $ pip install Theano --user
+
+Or for the bleeding-edge version:
+
+.. code-block:: bash
+
+    $ pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git

-.. _macports:

 MacPorts
 ~~~~~~~~
@@ -723,14 +749,6 @@ Theano dependencies is easy, but be aware that it will take a long time

        $ python -c "import theano; theano.test()"

-Homebrew
-~~~~~~~~
-
-There are some `instructions
-<https://github.com/samueljohn/homebrew-python>`__ by Samuel John on how to install
-Theano dependencies with Homebrew instead of MacPort.
-
-
 .. _gpu_macos:

 Using the GPU

--- a/doc/sandbox/index2.txt
+++ b/doc/sandbox/index2.txt
@@ -12,6 +12,5 @@ Advanced Topics (under construction)
    compilation
    ccodegen
    function
-    module
    debugging_with_stepmode