Merge pull request #2658 from abergeron/doc

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
 =======================
 

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

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

doc/sandbox/index2.txt

@@ -12,6 +12,5 @@ Advanced Topics (under construction)
     compilation
     ccodegen
     function
-    module
     debugging_with_stepmode