Tutorials for installing Python and Astropy, conda environments, and developer version of Astropy

.circleci/config.yml

@@ -13,7 +13,7 @@ pip-run: &pip-install
   command: |
     python3 -m venv venv
     . venv/bin/activate
-    pip install -q -r pip-requirements.txt
+    pip install -r pip-requirements.txt
     pip install astropy_helpers sphinx pytest
     pip install git+https://github.com/jupyter/nbconvert
 

.rtd-environment.yml

@@ -7,7 +7,7 @@ dependencies:
   - python=3.6
   - IPython=6.1.0
   - astropy=3
-  - astroquery=0.3.7
+  - astroquery>=0.3.7
   - matplotlib=2.0.2
   - numpy=1.14
   - scipy=1.0 # needed for coordinates cross-matching

environment.yml

@@ -7,7 +7,7 @@ dependencies:
   - python=3.6
   - IPython=6.1.0
   - astropy=3
-  - astroquery=0.3.7
+  - astroquery>=0.3.7
   - matplotlib=2.0.2
   - numpy=1.14
   - scipy=1.0 # needed for coordinates cross-matching

pip-requirements.txt

@@ -1,6 +1,6 @@
 IPython==6.1.0
 astropy==3
-astroquery==0.3.7
+astroquery>=0.3.7
 matplotlib==2.0.2
 numpy==1.14
 jupyter==1.0

scripts/convert.py

@@ -1,5 +1,6 @@
 # Standard library
 from os import path, walk, remove, makedirs
+import re
 
 # Third-party
 from astropy import log as logger
@@ -12,6 +13,15 @@
 
 IPYTHON_VERSION = 4
 
+def clean_keyword(kw):
+    """Given a keyword parsed from the header of one of the tutorials, return
+    a 'cleaned' keyword that can be used by the filtering machinery.
+
+    - Replaces spaces with capital letters
+    - Removes . / and space
+    """
+    return kw.strip().title().replace('.', '').replace('/', '').replace(' ', '')
+
 class NBTutorialsConverter(object):
 
     def __init__(self, nb_path, output_path=None, template_file=None,
@@ -45,10 +55,9 @@ def __init__(self, nb_path, output_path=None, template_file=None,
         self._rst_path = path.join(self.output_path,
                                    '{0}.rst'.format(self.nb_name))
 
-        if kernel_name is None:
-            self.kernel_name = ExecutePreprocessor.kernel_name.default_value
-        else:
-            self.kernel_name = kernel_name
+        self._execute_kwargs = dict(timeout=900)
+        if kernel_name:
+            self._execute_kwargs['kernel_name'] = kernel_name
 
     def execute(self, write=True):
         """
@@ -75,10 +84,9 @@ def execute(self, write=True):
             return self._executed_nb_path
 
         # Execute the notebook
-        logger.debug('Executing notebook using kernel '
-                     '"{}"...'.format(self.kernel_name))
-        executor = ExecutePreprocessor(timeout=900,
-                                       kernel_name=self.kernel_name)
+        logger.debug('Executing notebook using kwargs '
+                     '"{}"...'.format(self._execute_kwargs))
+        executor = ExecutePreprocessor(**self._execute_kwargs)
 
         with open(self.nb_path) as f:
             nb = nbformat.read(f, as_version=IPYTHON_VERSION)
@@ -140,6 +148,33 @@ def convert(self, remove_executed=False):
         output_file_path = writer.write(output, resources,
                                         notebook_name=self.nb_name)
 
+        # read the executed notebook, grab the keywords from the header,
+        # add them in to the RST as filter keywords
+        with open(self._executed_nb_path) as f:
+            nb = nbformat.read(f, as_version=IPYTHON_VERSION)
+
+        top_cell_text = nb['cells'][0]['source']
+        match = re.search('## [kK]eywords\s+(.*)', top_cell_text)
+
+        if match:
+            keywords = match.groups()[0].split(',')
+            keywords = [clean_keyword(k) for k in keywords if k.strip()]
+            keyword_filters = ['filter{0}'.format(k) for k in keywords]
+        else:
+            keyword_filters = []
+
+        # Add metatags to top of RST files to get rendered into HTML, used for
+        # the search and filter functionality in Learn Astropy
+        meta_tutorials = '.. meta::\n    :keywords: {0}\n'
+        filters = ['filterTutorials'] + keyword_filters
+        meta_tutorials = meta_tutorials.format(', '.join(filters))
+        with open(output_file_path, 'r') as f:
+            rst_text = f.read()
+
+        with open(output_file_path, 'w') as f:
+            rst_text = '{0}\n{1}'.format(meta_tutorials, rst_text)
+            f.write(rst_text)
+
         if remove_executed: # optionally, clean up the executed notebook file
             remove(self._executed_nb_path)
 

tutorials/01-conda_astropy_install.rst

@@ -0,0 +1,138 @@
+Installing Astropy and Related Packages with Anaconda
+=====================================================
+
+Pre-requisites
+--------------
+
+**Mac** Have the latest version of `Xcode
+developer <https://developer.apple.com/xcode/>`__ tools installed
+
+**Windows** Be able to access a terminal, either through a `Linux
+subsystem <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__
+or by installing the `Linux bash
+shell <https://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/>`__
+
+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 <https://www.astropy.org/affiliated/>`__ can be found on
+*astroconda* 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
+*astroconda* versus *conda-forge*. However, a package that is available
+in the *astroconda* channel may not be available in *conda-forge*.
+
+To see what channels you have available:
+
+::
+
+    conda config --show channels
+
+`More information on managing channels in
+Anaconda <https://conda.io/docs/user-guide/tasks/manage-channels.html>`__
+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 upgrade 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 <https://pypi.org/>`__ project
+also provides a package management program called `pip <https://pypi.org/project/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 may 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 <https://conda.io/docs/user-guide/tasks/manage-pkgs.html>`__.

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 <https://conda.io/docs/user-guide/install/download.html#anaconda-or-miniconda>`__
+
+-  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