Misc code and docs cleanup

docs/astro/source/index.rst

@@ -23,9 +23,6 @@ The following source models are available:
    pwn
    pulsar
 
-
-
-
 Reference/API
 =============
 

docs/development/index.rst

@@ -10,6 +10,33 @@ Note that Astropy has very extensive developer documentation
 `here <http://astropy.readthedocs.org/en/latest/#developer-documentation>`__,
 this page should only mention Gammapy-specific things.
 
+Where should I import from?
+---------------------------
+
+You should import from the "end-user namespaces", not the "implementation module".
+
+.. code-block:: python
+
+   from gammapy.data import EventList  # good
+   from gammapy.data.event_list import EventList # bad
+
+   from gammapy.stats import cash  # good
+   from gammapy.stats.fit_statistics import cash  # bad
+
+The end-user namespace is the location that is shown in the API docs, i.e. you can
+use the Sphinx full-text search to quickly find it.
+
+To make code maintenance easier, the implementation of the functions and classes is
+spread across multiple modules (`.py` files), but the user shouldn't care about their
+names, that would be too much to remember.
+
+The only reason to import from a module directly is if you need to access a private
+function, class or variable (something that is not listed in `__all__` and thus not
+imported into the end-user namespace. 
+
+Note that this means that in the definition of an "end-user namespace", e.g. in the
+``gammapy/data/__init__.py`` file, the imports have to be sorted in a way such that
+modules in ``gammapy/data`` are loaded when imported from other modules in that sub-package. 
 
 Why we don't sub-class other data classes
 _________________________________________
@@ -23,6 +50,7 @@ But in both cases, the data model didn't really fit our use cases for gamma-ray
 and so we decided to write our own data classes from scratch.
 
 Here's some issues where this was discussed:
+
 * https://github.com/radio-astro-tools/spectral-cube/issues/110
 * https://github.com/astropy/astropy/pull/2855#issuecomment-52610106
 

docs/index.rst

@@ -1,3 +1,5 @@
+.. include:: references.txt
+
 .. image:: _static/gammapy_banner.png
     :width: 400px
 
@@ -13,10 +15,10 @@ Currently the functionality is limited and geared towards Galactic plane survey
 but the idea is that Gammapy is a place to share and collaborate for gamma-ray astronomy Pythonistas
 ... contributions welcome! 
 
-* Read the `documentation <https://gammapy.readthedocs.org/>`__.
-* Ask questions on our `mailing list <http://groups.google.com/group/gammapy>`__.
-* Request features, report bugs or contribute on `our GitHub page <https://github.com/gammapy/gammapy>`__.
-* Check out the `project summary on Ohloh <https://www.ohloh.net/p/gammapy>`__
+* Read the `Gammapy documentation`_.
+* Ask questions on the `Gammapy mailing list`_.
+* Request features, report bugs or contribute on the `Gammapy GitHub page`_.
+* Check out the `Gammapy project summary on Ohloh`_ or the `Gammapy page on the PyPI`_.
 * Requires Python (version 2.7 and 3.3 or later), Numpy (version 1.6 or later) and Astropy (version 0.4 or later)
 
 General documentation
@@ -29,7 +31,6 @@ General documentation
   introduction
   scripts/index
   tutorials/index
-  examples/index
   dataformats/index
   references
   credit

docs/install.rst

@@ -5,20 +5,101 @@
 Installation
 ============
 
-To install the latest Gammapy stable version the easiest way is using the
-`pip <http://www.pip-installer.org/>`_ installer:
+Here we provide short installation instructions for Gammapy and its dependencies
+using the `pip`_ and `conda`_ tools.
+
+If you get stuck, have a look at the extensive installation instructions for Astropy
+at http://www.astropy.org/ or ask on the `Gammapy mailing list`_.
+
+Install Gammapy using pip
+-------------------------
+
+To install the latest Gammapy **stable** version using `pip`_:
 
 .. code-block:: bash
 
    $ pip install gammapy
 
-To install the latest developer version of Gammapy, use
+To install the current Gammapy **development** version using `pip`_:
+
+.. code-block:: bash
+
+   $ pip install git+https://github.com/gammapy/gammapy.git#egg=gammapy
+
+Download and install Gammapy manually
+-------------------------------------
+
+To download the latest stable version of Gammapy, download it from
+https://pypi.python.org/pypi/gammapy, if you have the
+`wget <http://www.gnu.org/software/wget/>`_ tool available you can do this
+from the command line:
+
+.. code-block:: bash
+
+   $ wget https://pypi.python.org/packages/source/g/gammapy/gammapy-0.1.tar.gz  
+   $ tar zxf gammapy-0.1.tar.gz
+   $ cd gammapy-0.1
+
+To download the latest development version of Gammapy:
 
 .. code-block:: bash
 
    $ git clone https://github.com/gammapy/gammapy.git
    $ cd gammapy
-   $ python setup.py install --user
+
+Either way, you now can install, test or build the documentation:
+
+.. code-block:: bash
+
+   $ python setup.py install
+   $ python setup.py test
+   $ python setup.py build_sphinx
+
+Also you have easy access to the Python scripts from the tutorials and examples: 
+
+.. code-block:: bash
+
+   $ cd docs/tutorials
+   $ cd examples
+
+If you want to contribute to Gammapy, but are not familiar with Python or
+git or Astropy yet, please have a look at the  
+`Astropy developer documentation <http://docs.astropy.org/en/latest/#developer-documentation>`__.
+
+Install Gammapy and its dependencies using Conda
+------------------------------------------------
+
+In the past it has often been hard to install Python packages and all their dependencies.
+Not any more ... using `conda`_ you can install Gammapy and most of its dependencies on
+any Linux machine or Mac in 5 minutes (without needing root access on the machine).
+
+Go to http://conda.pydata.org/miniconda.html and download the installer for your system,
+e.g. currently for Linux and Mac you can use:
+
+.. code-block:: bash
+
+   $ wget http://repo.continuum.io/miniconda/Miniconda3-3.6.0-Linux-x86_64.sh -O miniconda.sh
+   $ wget http://repo.continuum.io/miniconda/Miniconda3-3.6.0-MacOSX-x86_64.sh -O miniconda.sh
+
+Then install binary packages using ``conda`` and source packages using ``pip`` by
+copy & pasting the following lines into your terminal:
+
+.. code-block:: bash
+
+   bash miniconda.sh -b -p $PWD/miniconda
+   export PATH="$PWD/miniconda/bin:$PATH"
+   conda config --set always_yes yes --set changeps1 no
+   conda update -q conda
+   conda install pip scipy matplotlib scikit-image astropy
+   pip install reproject aplpy
+   pip install gammapy
+
+Overall ``conda`` is a great cross-platform package manager, you can quickly learn how to use
+it by reading the docs here: http://conda.pydata.org/docs/
+
+
+Check if your Gammapy installation is OK
+----------------------------------------
 
 To check if Gammapy is correctly installed, start up python or ipython,
 import Gammapy and run the unit tests:
@@ -33,10 +114,13 @@ To check if the Gammapy command line tools are on your ``$PATH`` try this:
 
    $ gammapy-info --tools
 
+.. _install-requirements:
+
 Requirements
 ------------
 
 Gammapy works with Python 2 and 3.
+
 More specifically, in the Python 2 series we only support Python 2.7,
 and in the Python 3 series we support version 3.3 or later.
 Gammapy will not work with Python 2.6 or 3.2
@@ -58,11 +142,11 @@ Optional dependencies (imported and used only where needed):
 * `imageutils`_ for image utility functions (temporary, will become `astropy.image`)
 * `reproject`_ for image reprojection (temporary, will become `astropy.reproject`)
 
-.. note:: I didn't put any effort into minimizing the number of dependencies ...
+.. note:: We didn't put any effort into minimizing the number of dependencies ...
    I'll limit the number of optional packages if people complain about installation woes.
 
-Sherpa
-------
+How to make Astropy / Gammapy work with the CIAO Sherpa Python?
+---------------------------------------------------------------
 
 Some parts of Gammapy use the `Sherpa`_ Python modeling / fitting package
 from the `CIAO`_ Chandra satellite X-ray data analysis package. 
@@ -104,3 +188,16 @@ Here's a few tricks that might help you make it work.
 
    $ export PATH=$CIAO_DIR/ots/bin:$PATH
    $ export PYTHONPATH=$CIAO_DIR/ots/lib/python2.7/site-packages/:$PYTHONPATH
+
+How to make Astropy / Gammapy work with the Fermi ScienceTools Python?
+----------------------------------------------------------------------
+
+Try installing `pip`_ into that Python and then:
+
+.. code-block:: bash
+
+   $ pip install astropy
+   $ pip install gammapy
+
+If this doesn't work (which is not uncommon, this is known to fail to compile the C extensions of Astropy
+on some platforms), ask your Python-installation-savvy co-worker or on the Astropy or Gammapy mailing list.

docs/references.txt

@@ -16,4 +16,11 @@
 .. _aplpy: http://aplpy.github.io
 .. _matplotlib: http://matplotlib.org
 .. _pandas: http://pandas.pydata.org
-
+.. _pip: http://www.pip-installer.org/
+.. _conda: http://conda.pydata.org/
+
+.. _Gammapy mailing list: http://groups.google.com/group/gammapy
+.. _Gammapy Github page: https://github.com/gammapy/gammapy
+.. _Gammapy documentation: https://gammapy.readthedocs.org/
+.. _Gammapy project summary on Ohloh: https://www.ohloh.net/p/gammapy
+.. _Gammapy page on PyPI: https://pypi.python.org/pypi/gammapy 

docs/tutorials/index.rst

@@ -1,8 +1,22 @@
 .. _tutorials:
 
-*********
-Tutorials
-*********
+**********************
+Tutorials and Examples
+**********************
+
+We currently have three places for Gammapy tutorials and examples:
+
+1. Python scripts with Sphinx documentation in the ``docs/tutorials`` folder in the ``gammapy`` repo.
+2. Python scripts without inline comments only in the ``examples`` folder in the ``gammapy`` repo.
+3. IPython notebooks in the ``notebooks`` folder in the ``gammapy-extra`` repo.
+
+Each of these solutions has advantages / disadvantages, we might consolidate this in the future as
+the tooling to convert between these formats improves.
+
+.. _tutorials-sphinx:
+
+Python example scripts with Sphinx documentation
+================================================
 
 The tutorials show some real-world usage examples of the Gammapy Python package and / or command line tools.
 
@@ -16,6 +30,29 @@ The tutorials show some real-world usage examples of the Gammapy Python package
    gammapy-pfmap/index
    gammapy-pfspec/index
 
+.. _tutorials-examples:
+
+Python example scripts
+======================
+
+The ``examples`` folder in the ``gammapy`` repo contains small Python scripts
+illustrating how to use Gammapy.
+
+.. note:: For now the full list of examples is only available here:
+   https://github.com/gammapy/gammapy/tree/master/examples
+
+   We plan to integrate that into the online Sphinx docs ...
+   please help if you know how to do this:
+   https://github.com/gammapy/gammapy/issues/172
+
+.. _tutorials-notebook:
+
+IPython notebooks
+=================
+
+The IPython notebooks are in the `gammapy-extra <https://github.com/gammapy/gammapy-extra>`__ repo,
+see `here <http://nbviewer.ipython.org/github/gammapy/gammapy-extra/blob/master/notebooks/Index.ipynb>`__. 
+
 External
 ========
 

docs/tutorials/npred/index.rst

@@ -15,9 +15,9 @@ Predicting Counts
 -----------------
 
 The example script below computes the Fermi PSF-convolved predicted counts map
-using `gammapy.spectral_cube`. This is then used to produce a Li & Ma significance
-image [LiMa1983]_. The left image shows the significance image produced using the
-methods in `gammapy.spectral_cube`, while a comparison against the significance image
+using `~gammapy.data.SpectralCube`. This is then used to produce a Li & Ma significance
+image [LiMa1983]_. The left image shows the significance image,
+while a comparison against the significance image
 produced using the Fermi Science tools is shown on the right. These results are
 for the Vela region for energies between 10 and 500 GeV.
 

gammapy/astro/population/__init__.py

@@ -2,6 +2,6 @@
 """
 Astrophysical population models
 """
-from .simulate import *
 from .spatial import *
 from .velocity import *
+from .simulate import *

gammapy/astro/population/simulate.py

@@ -3,7 +3,7 @@
 """
 from __future__ import print_function, division
 import numpy as np
-from numpy import sqrt, degrees, pi, arctan, arctan2, exp
+from numpy import degrees, pi, arctan, exp
 from numpy.random import uniform, normal
 from astropy.table import Table, Column
 from astropy.units import Quantity
@@ -13,11 +13,10 @@
 from ...utils.const import d_sun_to_galactic_center
 from ...utils.distributions import draw, pdf
 from ...morphology.shapes import morph_types
-from ..source import SNR, PWN, Pulsar
 from ...catalog.utils import as_quantity
-from .spatial import Exponential, FaucherSpiral, RMIN, RMAX, ZMIN, ZMAX, radial_distributions
-from .velocity import VMIN, VMAX, velocity_distributions
-from gammapy.astro.source.snr import SNRTrueloveMcKee
+from ..source import SNR, SNRTrueloveMcKee, PWN, Pulsar
+from ..population import Exponential, FaucherSpiral, RMIN, RMAX, ZMIN, ZMAX, radial_distributions
+from ..population import VMIN, VMAX, velocity_distributions
 
 
 __all__ = ['make_cat_cube',

gammapy/astro/population/spatial.py

@@ -11,19 +11,18 @@
 from __future__ import print_function, division
 import numpy as np
 from numpy.random import random_integers, uniform, normal
-
 from numpy import exp, pi, log, abs, cos, sin
 from astropy.units import Quantity
 from astropy.utils.compat.odict import OrderedDict
 from astropy.modeling import Fittable1DModel, Parameter
 from ...utils.coordinates import cartesian, polar
-
 from ...utils.const import d_sun_to_galactic_center
 
 __all__ = ['CaseBattacharya1998', 'FaucherKaspi2006', 'Lorimer2006',
            'Paczynski1990', 'YusifovKucuk2004', 'YusifovKucuk2004B',
            'Exponential', 'LogSpiral', 'FaucherSpiral', 'ValleeSpiral',
-           'radial_distributions'
+           'radial_distributions',
+           'RMIN', 'RMAX', 'ZMIN', 'ZMAX',
            ]
 
 R_SUN_GALACTIC = d_sun_to_galactic_center.value