diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7041dbabdad5..d3eeb820a12eb 100644 --- a/CONTRIBUTING.md +++ b/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 \ or + Install miniconda \ +- Make sure that you have + cloned the repository \ +- `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 \, 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** > diff --git a/ci/requirements_all.txt b/ci/requirements_all.txt new file mode 100644 index 0000000000000..c70efed96a8dd --- /dev/null +++ b/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 diff --git a/ci/requirements_dev.txt b/ci/requirements_dev.txt new file mode 100644 index 0000000000000..b273ca043c4a2 --- /dev/null +++ b/ci/requirements_dev.txt @@ -0,0 +1,5 @@ +dateutil +pytz +numpy +cython +nose diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index b3b2d272e66c6..cc4473e8d355a 100644 --- a/doc/source/contributing.rst +++ b/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 ` or :ref:`Install miniconda ` +- Make sure that you have :ref:`cloned the repository ` +- ``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 +`_. + +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 `, then install: + +:: + + conda install -n pandas_dev sphinx ipython + Furthermore, it is recommended to have all `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 - - - diff --git a/doc/source/install.rst b/doc/source/install.rst index dd9021d0439dc..07c88841e5dcb 100644 --- a/doc/source/install.rst +++ b/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 `__ 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 - `__ 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 ` for complete instructions on building from the git source tree. Further, see :ref:`creating a devevlopment environment ` 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 `__ may be worth considering. -