Merge pull request #9810 from jreback/dev

DOC: add dev environment creation details to contributing.rst

Author: jreback

CONTRIBUTING.md

@@ -137,6 +137,69 @@ clear what the branch brings to *pandas*. You can have many
 shiny-new-features and switch in between them using the git checkout
 command.
 
+### Creating a Development Environment
+
+An easy way to create a *pandas* development environment is as follows.
+
+-   Install either Install Anaconda \<install-anaconda\> or
+    Install miniconda \<install-miniconda\>
+-   Make sure that you have
+    cloned the repository \<contributing-forking\>
+-   `cd` to the pandas source directory
+
+Tell `conda` to create a new environment, named `pandas_dev`, or any
+name you would like for this environment by running:
+
+    conda create -n pandas_dev --file ci/requirements_dev.txt
+
+For a python 3 environment
+
+    conda create -n pandas_dev python=3 --file ci/requirements_dev.txt
+
+If you are on `windows`, then you will need to install the compiler
+linkages:
+
+    conda install -n pandas_dev libpython
+
+This will create the new environment, and not touch any of your existing
+environments, nor any existing python installation. It will install all
+of the basic dependencies of *pandas*, as well as the development and
+testing tools. If you would like to install other dependencies, you can
+install them as follows:
+
+    conda install -n pandas_dev -c pandas pytables scipy
+
+To install *all* pandas dependencies you can do the following:
+
+    conda install -n pandas_dev -c pandas --file ci/requirements_all.txt
+
+To work in this environment, `activate` it as follows:
+
+    activate pandas_dev
+
+At which point, the prompt will change to indicate you are in the new
+development environment.
+
+> **note**
+>
+> The above syntax is for `windows` environments. To work on
+> `macosx/linux`, use:
+>
+>     source activate pandas_dev
+
+To view your environments:
+
+    conda info -e
+
+To return to you home root environment:
+
+    deactivate
+
+See the full `conda` docs [here](http://conda.pydata.org/docs).
+
+At this point you can easily do an *in-place* install, as detailed in
+the next section.
+
 ### Making changes
 
 Before making your code changes, it is often necessary to build the code
@@ -231,13 +294,19 @@ docstrings that follow the Numpy Docstring Standard (see above), but you
 don't need to install this because a local copy of `numpydoc` is
 included in the *pandas* source code.
 
+It is easiest to
+create a development environment \<contributing-dev\_env\>, then
+install:
+
+    conda install -n pandas_dev sphinx ipython
+
 Furthermore, it is recommended to have all [optional
 dependencies](http://pandas.pydata.org/pandas-docs/dev/install.html#optional-dependencies)
-installed. This is not needed, but be aware that you will see some error
-messages. Because all the code in the documentation is executed during
-the doc build, the examples using this optional dependencies will
-generate errors. Run `pd.show_versions()` to get an overview of the
-installed version of all dependencies.
+installed. This is not strictly necessary, but be aware that you will
+see some error messages. Because all the code in the documentation is
+executed during the doc build, the examples using this optional
+dependencies will generate errors. Run `pd.show_versions()` to get an
+overview of the installed version of all dependencies.
 
 > **warning**
 >

ci/requirements_all.txt

@@ -0,0 +1,21 @@
+nose
+sphinx
+ipython
+dateutil
+pytz
+openpyxl
+xlsxwriter
+xlrd
+html5lib
+patsy
+beautiful-soup
+numpy
+cython
+scipy
+numexpr
+pytables
+matplotlib
+lxml
+sqlalchemy
+bottleneck
+pymysql

ci/requirements_dev.txt

@@ -0,0 +1,5 @@
+dateutil
+pytz
+numpy
+cython
+nose

doc/source/contributing.rst

@@ -96,6 +96,8 @@ Getting Started with Git
 setting up your SSH key, and configuring git.  All these steps need to be completed before
 working seamlessly with your local repository and GitHub.
 
+.. _contributing.forking:
+
 Forking
 -------
 
@@ -132,6 +134,84 @@ changes in this branch specific to one bug or feature so it is clear
 what the branch brings to *pandas*. You can have many shiny-new-features
 and switch in between them using the git checkout command.
 
+.. _contributing.dev_env:
+
+Creating a Development Environment
+----------------------------------
+
+An easy way to create a *pandas* development environment is as follows.
+
+- Install either :ref:`Install Anaconda <install-anaconda>` or :ref:`Install miniconda <install-miniconda>`
+- Make sure that you have :ref:`cloned the repository <contributing-forking>`
+- ``cd`` to the pandas source directory
+
+Tell ``conda`` to create a new environment, named ``pandas_dev``, or any name you would like for this environment by running:
+
+::
+
+      conda create -n pandas_dev --file ci/requirements_dev.txt
+
+
+For a python 3 environment
+
+::
+
+      conda create -n pandas_dev python=3 --file ci/requirements_dev.txt
+
+
+If you are on ``windows``, then you will need to install the compiler linkages:
+
+::
+
+      conda install -n pandas_dev libpython
+
+This will create the new environment, and not touch any of your existing environments, nor any existing python installation. It will install all of the basic dependencies of *pandas*, as well as the development and testing tools. If you would like to install other dependencies, you can install them as follows:
+
+::
+
+      conda install -n pandas_dev -c pandas pytables scipy
+
+To install *all* pandas dependencies you can do the following:
+
+::
+
+      conda install -n pandas_dev -c pandas --file ci/requirements_all.txt
+
+To work in this environment, ``activate`` it as follows:
+
+::
+
+      activate pandas_dev
+
+At which point, the prompt will change to indicate you are in the new development environment.
+
+.. note::
+
+   The above syntax is for ``windows`` environments. To work on ``macosx/linux``, use:
+
+   ::
+
+       source activate pandas_dev
+
+To view your environments:
+
+::
+
+      conda info -e
+
+To return to you home root environment:
+
+::
+
+      deactivate
+
+See the full ``conda`` docs `here
+<http://conda.pydata.org/docs>`_.
+
+At this point you can easily do an *in-place* install, as detailed in the next section.
+
+.. _contributing.getting_source:
+
 Making changes
 --------------
 
@@ -237,9 +317,15 @@ follow the Numpy Docstring Standard (see above), but you don't need to install
 this because a local copy of ``numpydoc`` is included in the *pandas* source
 code.
 
+It is easiest to :ref:`create a development environment <contributing-dev_env>`, then install:
+
+::
+
+      conda install -n pandas_dev sphinx ipython
+
 Furthermore, it is recommended to have all `optional dependencies
 <http://pandas.pydata.org/pandas-docs/dev/install.html#optional-dependencies>`_
-installed. This is not needed, but be aware that you will see some error
+installed. This is not strictly necessary, but be aware that you will see some error
 messages. Because all the code in the documentation is executed during the doc
 build, the examples using this optional dependencies will generate errors.
 Run ``pd.show_versions()`` to get an overview of the installed version of all
@@ -572,6 +658,3 @@ branch has not actually been merged.
 The branch will still exist on GitHub, so to delete it there do ::
 
     git push origin --delete shiny-new-feature
-
-
-

doc/source/install.rst

@@ -35,6 +35,8 @@ pandas at all.
 Simply create an account, and have access to pandas from within your brower via
 an `IPython Notebook <http://ipython.org/notebook.html>`__ in a few minutes.
 
+.. _install.anaconda
+
 Installing pandas with Anaconda
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -66,6 +68,8 @@ admin rights to install it, it will install in the user's home directory, and
 this also makes it trivial to delete Anaconda at a later date (just delete
 that folder).
 
+.. _install.miniconda
+
 Installing pandas with Miniconda
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -173,47 +177,8 @@ Installing using your Linux distribution's package manager.
 
 Installing from source
 ~~~~~~~~~~~~~~~~~~~~~~
-.. note::
-
-   Installing from the git repository requires a recent installation of `Cython
-   <http://cython.org>`__ as the cythonized C sources are no longer checked
-   into source control. Released source distributions will contain the built C
-   files. I recommend installing the latest Cython via ``easy_install -U
-   Cython``
-
-The source code is hosted at http://github.com/pydata/pandas, it can be checked
-out using git and compiled / installed like so:
-
-::
-
-  git clone git://github.com/pydata/pandas.git
-  cd pandas
-  python setup.py install
-
-Make sure you have Cython installed when installing from the repository,
-rather then a tarball or pypi.
 
-On Windows, I suggest installing the MinGW compiler suite following the
-directions linked to above. Once configured property, run the following on the
-command line:
-
-::
-
-  python setup.py build --compiler=mingw32
-  python setup.py install
-
-Note that you will not be able to import pandas if you open an interpreter in
-the source directory unless you build the C extensions in place:
-
-::
-
-  python setup.py build_ext --inplace
-
-The most recent version of MinGW (any installer dated after 2011-08-03)
-has removed the '-mno-cygwin' option but Distutils has not yet been updated to
-reflect that. Thus, you may run into an error like "unrecognized command line
-option '-mno-cygwin'". Until the bug is fixed in Distutils, you may need to
-install a slightly older version of MinGW (2011-08-02 installer).
+See the :ref:`contributing documentation <contributing>` for complete instructions on building from the git source tree. Further, see :ref:`creating a devevlopment environment <contributing-dev_env>` if you wish to create a *pandas* development environment.
 
 Running the test suite
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -354,4 +319,3 @@ Optional Dependencies
    work. Hence, it is highly recommended that you install these. A packaged
    distribution like `Enthought Canopy
    <http://enthought.com/products/canopy>`__ may be worth considering.
-