diff --git a/tutorials/01-conda_astropy_install.rst b/tutorials/01-conda_astropy_install.rst new file mode 100644 index 000000000..40d916481 --- /dev/null +++ b/tutorials/01-conda_astropy_install.rst @@ -0,0 +1,148 @@ +Installing Astropy and Related Packages with Anaconda +===================================================== + +Pre-requisites +-------------- + +**Mac** Have the latest version of `Xcode +developer `__ tools installed + +**Windows** Be able to access a terminal, either through a `Linux +subsystem `__ +or by installing the `Linux bash +shell `__ + +Step 1: Download Anaconda +------------------------- + +The Anaconda Python distribution can be downloaded from +https://www.anaconda.com/download + +- The scientific computing community is now using Python 3 as a + default. + +**But my code only runs in Python 2** Please see the next tutorial: *An +Astropy User's Guide to Managing Conda Environments* + +- When the download is finished, click on the package and follow the + installation instructions. + +- Open a terminal window to check that the Anaconda installation will + work for you: + + :: + + which conda + + should return something like ``/anaconda3/bin/conda`` and + + :: + + which python + + should return a Python path that is in the same directory as + Anaconda: ``/anaconda3/bin/python`` + +Step 2: Install core packages +----------------------------- + +The default Anaconda installation comes with many packages that +astronomers use frequently: *numpy*, *scipy*, and *matplotlib* + +We can use the ``conda install`` command to install everything else we +need. Anaconda will automatically check, update, and install any python +packages that your desired package depends on. + +- Below, we give an example of installing astropy along with some common + scientific, statistical, and visualization packages. You can install them all + individually or in one line: + +:: + + conda install astropy matplotlib scikit-learn pandas + +Step 3: Install affiliated packages +----------------------------------- + +Many `Astropy affiliated +packages `__ can be found on +*astropy* channel, maintained by AURA and STScI. To add this channel +to Anaconda's package search list, run the following command: + +:: + + conda install --channel "astropy" package + +Some astronomical packages are also available in the *conda-forge* +channel. There is no wrong choice between installing a package from +*astropy* versus *conda-forge*. However, a package that is available +in the *astropy* channel may not be available in *conda-forge*. + +Note also that there is an `*astroconda* channel managed by STScI +`__ +that includes IRAF/pyraf and several other modern packages. + +To see what channels you have available: + +:: + + conda config --show channels + +`More information on managing channels in +Anaconda `__ +is available on the main documentation pages. + +- Here's an example for downloading a few commonly used Astropy + affiliated packages, directly from the *astropy* channel: + + :: + + conda install -c astropy photutils specutils + +**Note:** If you plan to use the ``astroquery`` package, we recommend using ``pip install`` instead of ``conda install``. See the *Conda vs Pip* discussion, below. + +Additional materials +==================== + +How to upgrade a package or install a specific version +------------------------------------------------------ + +To upgrade to the latest version of Astropy: + +:: + + conda update astropy + +You can choose a specific Astropy version using: + +:: + + conda install astropy=2.0 + +Conda vs Pip +------------ + +Anaconda is one of several package management systems that you might use +for Python. The `Python Package Index `__ project +also provides a package management program called `pip `__. + +Generally, you should pick one package management system and stick to +it. However, there may be cases where a package is available with +``pip`` and not ``conda``, or vice versa. + +With Anaconda, you can still use ``pip`` to download and install +software within the conda environment of your choice. However, +conflicts will arise if you ``pip install`` a package that has already +been installed with ``conda``, or vice versa. So once you use ``pip`` +to install a package, you should use ``pip`` to update and manage that +package. + +**In particular, we recommend using `pip` to manage the `astroquery` + package.** This library is under continuous development. The latest + versions and bug-fixes are more readily available with ``pip``, + because it takes a long time for the ``conda`` distribution to + update. + +Further documentation on this topic is available on the `conda package +management documentation +page `__. diff --git a/tutorials/02-conda_envs.rst b/tutorials/02-conda_envs.rst new file mode 100644 index 000000000..38fd8b7e4 --- /dev/null +++ b/tutorials/02-conda_envs.rst @@ -0,0 +1,115 @@ +An Astropy User's Guide to Managing Conda Environments and Jupyter Notebook +=========================================================================== + + + Help! My code library works in Python 2 and I don't have time to + make it work in Python 3 + +Do not fear! This tutorial will teach you how to use conda environments +to create a *separate* installation of Python 2.7. With conda +environments, you can switch between Python 2 and 3 without having to +worry about version conflicts. + +Step 1: Set up a Python 2 environment +------------------------------------- + +- Create a new ``conda`` environment + + :: + + conda create -n python2 python=2.7 anaconda + +**NOTE:** By adding ``anaconda`` at the end, the complete Anaconda Python distribution will be installed. Omitting ``anaconda`` or choosing ``miniconda`` will install a much smaller library of Python packages. You can install any additional packages you need for that environment, after activating it. `Some information about the differences between Anaconda and Miniconda can be found in the conda document pages `__ + +- Activate the Python 2 environment and install any additional packages + you need to run your favorite code library. Here, we show you how to + install the base version of Astropy. + + :: + + source activate python2 + conda install astropy + +**NOTE:** If you want to install Astropy and **all** affiliated packages, you can use `` conda install stsci`` + +- When you are ready to return to your default environment: + + :: + + source deactivate + +**NOTE:** Some newer versions of Anaconda use ``conda activate`` and +``conda deactivate``. In that case, both ``source`` and ``conda`` will work +interchangeably when activating or deactivating your chosen environment. + +When you want to see all of your available environments: + +:: + + conda env list + +Step 2: Check that your code runs in the new environment +-------------------------------------------------------- + +- Now you are ready to work in Python 2! Here's a generic example for + switching to your Python 2 environment, running your Python 2 script, + and exiting the environment. + + :: + + cd ~/my-python2-library + source activate python2 + python my_python2_script.py + source deactivate + +Step 3: Set up a Jupyter Notebook for the new environment +--------------------------------------------------------- + +- Activate your custom Python 2 environment: + + :: + + source activate python2 + +- Check that you have ipykernel installed + + :: + + conda list | grep ipykernel + +If you do not see any output, install it with +``conda install ipykernel`` + +- Install that environment for Jupyter notebook. In this case, we are + choosing a display name, "python2", that matches the environment name, + but you may choose something else. + + :: + + python -m ipykernel install --user --name python2 --display-name "python2"` + +- Now leave that environement + + :: + + source deactivate + +- Start a Jupyter Notebook session + + :: + + jupyter notebook + +- When you click on *New*, you should see a drop down list of options + that include "python2", the environment display name we chose above. + +- If you would like to change the environment for an existing Jupyter + Notebook, click on *Kernel*, then *Change kernel*, and select the + environment you would like to use. + +- In general, you can view your available Jupyter Notebook kernels by + running + + :: + + jupyter kernelspec list diff --git a/tutorials/03-astropy_dev_env.rst b/tutorials/03-astropy_dev_env.rst new file mode 100644 index 000000000..a3e4f567c --- /dev/null +++ b/tutorials/03-astropy_dev_env.rst @@ -0,0 +1,178 @@ +How to set up a development version of Astropy +============================================== + +Found a bug? Know how to fix it? See a modification you need for your +own project? This tutorial will teach you how to set up a conda +environment for installing and modifying a developer version of Astropy. + +Pre-requisites +-------------- + +- `Git `__ version control system. On a Mac, this + will come with installing the latest version of the `Xcode + developer `__ tools. +- An account on `GitHub `__ + +This tutorial will show you how to fork, clone, and install the +development version of Astropy from the command line (terminal). + +Step 1: Fork the Astropy repo on Github +--------------------------------------- + +- Log into your account on Github +- Go to https://github.com/astropy/astropy and click on **Fork** in the + upper right-hand corner of the page. This will create a separate repo + in your Github account under github.com//astropy + +Step 2: Clone your forked Astropy repo to your computer +------------------------------------------------------- + +- Go to your forked version of the repository and click on **Clone or + download** (the green button on the upper right-hand side of the + page). +- Highlight and copy the revealed URL. If you prefer using SSH to + connect to Github, you can toggle between "Use SSH" and "Use HTTPS" + by clicking on the highlighted text in the upper right-hand corner of + the box. +- Open a terminal session +- Make an astropy folder in the location you would like to develop the + code. For example: + + :: + + mkdir astropy-dev + cd astropy-dev + git clone git@github.com:/astropy.git . + +**IMPORTANT NOTE:** If it has been a long time since you forked the +Astropy repo for the first time, your fork may out of date. Before +proceeding, follow the instructions for **Keeping your fork up to date** +at the bottom of this page. + +Step 3: Create a new conda environment for developing astropy +------------------------------------------------------------- + +- Inside the astropy-dev folder, create a new conda environment called + *astropy-dev* and activate it. + + :: + + conda create -n astropy-dev --only-deps python=3 astropy + source activate astropy-dev + + The *--only-deps* flag indicates that the new environment will be installed with all of astropy's dependencies without installing astropy itself. + +- Inside the astropy-dev folder, install the Astropy from the source + code: + + :: + + python setup.py develop + + The *develop* command will install the package in way that does not require you to re-install any time you make changes to your astropy-dev library. + +- At this point, you could install any other packages you normally work + with, *except* for astropy. For example, + + :: + + conda install pandas + +Step 4: Make a new branch for editing the source code +----------------------------------------------------- + +- Inside the astropy-dev folder, create a new branch to work in. Try to + pick a descriptive name for your branch: + + :: + + git branch my-code-update + git checkout my-code-update + +Congratulations! You're ready to edit the astropy source code safely. +Use ``git`` for committing your changes and pushing those changes to +your ``my-code-update`` branch on Github. + +Here's an example of creating a new file and pushing it to the new branch: + +:: + + echo "print('hello world')" > my-new-code.py + git add my-new-code.py + git commit -m "first commit" + git push origin my-code-update + +For more help with learning Git and Github, see the `Github +Help `__ pages, the `Git and Github Learning +Resources `__ +guide, `try.github.io `_, and the `Github Learning Lab `_ + +When you are done working on development, don't forget to exit the +astropy-dev environment. + +:: + + source deactivate + +When you want your changes to be incorporated into Astropy, `submit a pull request on Github `__. If you're looking for `quick ways to contribute to Astropy `__, check out the issues page on the main Astropy Github repo. + + +Keeping your fork up to date +============================ + +If it has been awhile since you last forked the Astropy repo, your fork +will likely need updating. This tutorial will teach you how to use the +command line to connect to the main Astropy Github repo, update to the +latest development version, and push those changes to your personal +Astropy fork on Github. + +Step 1: Add the core Astropy repo to your git config file +--------------------------------------------------------- + +- Go to https://github.com/astropy/astropy and click on the green + "Clone or Download" button in the upper right-hand corner of the + page. +- Go to the directory where you have the Astropy repo on your computer, + for example: + + :: + + cd ~/astropy-dev + +- Add a new remote named *upstream* to your local copy of the Astropy + repo + + :: + + git remote add upstream git@github.com:astropy/astropy.git + +Step 2: Pull any changes from the master branch of the main Astropy repo +------------------------------------------------------------------------ + +- Make sure you are in the master branch of your local Astropy repo + + :: + + git checkout master + +- Use ``git pull`` to update your local master branch from the upstream + Astropy master branch + + :: + + git pull upstream master + +Step 3: Push the changes to your fork on Github +----------------------------------------------- + +- Use ``git push`` to update your Github fork of Astropy: + + :: + + git push origin master + + If you've already made some changes to your own master branch, you may need to force the push with the `--force` command. This may cause you to lose some changes or issues with your git history. This is why it's good practice to **always develop in a separate branch**. + + + +Congratulations! You are up to date!