Reorganise scripts filenames and add docs for scripts.

Also update getting started a bit.

docs/getting-started.rst

@@ -0,0 +1,100 @@
+.. include:: references.txt
+
+.. _getting-started:
+
+Getting Started
+===============
+
+Introduction
+------------
+
+New to Gammapy? You came to the right place!
+
+Gammapy is a Python package, consisting of functions and classes, that you can use
+as a flexible and extensible toolbox to implement and execute exactly the analysis you want.
+
+In addition, Gammapy provides some command line tools
+(and we're starting to add web apps with a graphical user interface)
+that make it easy to perform common tasks simply by specifying a command and some parameters as arguments,
+no Python programming needed.
+
+This is a 5 minute tutorial that shows you how get started using Gammapy as a package or command line tool.
+
+If you'd like to follow along, make sure you have Gammapy installed (see :ref:`installation`).
+
+If you're new to Python for gamma-ray astronomy and would like to learn the basics, we recommend
+you go to the `Scipy Lecture Notes`_ or the `Practical Python for Astronomers Tutorial`_.
+
+Using Gammapy as a Python package
+---------------------------------
+
+Here's a few very simple examples how to use Gammapy as a Python package.
+
+What's the statistical significance when 10 events have been observed with a known background level of 4.2
+according to [LiMa1983]_?
+
+Call the `~gammapy.stats.significance` function:
+
+.. code-block:: python
+
+   >>> from gammapy.stats import significance
+   >>> significance(n_observed=10, mu_background=4.2, method='lima')
+   2.3979181291475453
+
+What's the differential gamma-ray flux and spectral index of the Crab nebula at 3 TeV
+according to [Meyer2010]_?
+
+Call the `~gammapy.spectrum.crab_flux` and `~gammapy.spectrum.crab_spectral_index` functions:
+
+.. code-block:: python
+
+   >>> from gammapy.spectrum import crab_flux, crab_spectral_index
+   >>> crab_flux(energy=3, reference='meyer')
+   1.8993523278650278e-12
+   >>> crab_spectral_index(energy=3, reference='meyer')
+   2.6763224503600429
+
+All functionality is in subpackages (e.g. `gammapy.stats` or `gammapy.spectrum`) ...
+browse their docs to see if it contains the methods you want.
+
+Using Gammapy as a command line tool
+------------------------------------
+
+This section contains a few examples how to use Gammapy as a command line tool.
+
+Say you have a counts and background model image and would like to compute
+a significance image with a correlation radius of 0.1 deg:
+
+.. code-block:: bash
+
+   $ gammapy-make-derived-maps --in counts.fits background.fits \
+                               --meaning counts background \
+                               --out significance.fits \
+                               --correlation_radius 0.1
+
+Say you have an image that contains the `Crab nebula`_
+and want to look up the map value at the Crab position
+(name lookup is done with `SIMBAD`_):
+
+.. code-block:: bash
+
+   $ gammapy-lookup-map-values crab_image.fits --object "Crab"
+
+You can call ``gammapy-tool-name --help`` or ``gammapy-tool-name -h`` for any tool.
+
+More information on tools and a list of all available tools can be found in :ref:`scripts`.
+
+What next?
+----------
+
+If you'd like to continue with tutorials to learn Gammapy, go to :ref:`tutorials`.
+
+To learn about some specific functionality that could be useful for your work,
+start browsing the "Getting Started" section of Gammapy sub-package that
+might be of interest to you (e.g. `gammapy.spectrum`, `gammapy.obs`, `gammapy.catalog`, ...).
+
+Not sure if Gammapy has the feature you want or how to do what you want?
+Ask for help on the `Gammapy mailing list`_.
+
+.. _Crab nebula: http://en.wikipedia.org/wiki/Crab_Nebula
+.. _SIMBAD: http://simbad.u-strasbg.fr/simbad

docs/index.rst

@@ -16,9 +16,11 @@ Gammapy is a community-developed, open-source Python package for gamma-ray astro
 * Ask questions on the `Gammapy mailing list`_.
 * Request features, report bugs or contribute on the `Gammapy GitHub page`_.
 
-If you're new to Gammapy, have a look at the :ref:`about` and :ref:`introduction` pages.
+To learn more about Gammapy, have a look at the :ref:`about` page, which includes
+a link to the Gammapy proceeding from ICRC 2015.
 
-If you'd like to try out Gammapy, head over to the :ref:`install` and :ref:`tutorials`.
+To get started with Gammapy, follow the instructions in the :ref:`install` page,
+and then head over to the 5 minute :ref:`getting-started` tutorial.
 
 .. _gammapy_news:
 
@@ -47,7 +49,7 @@ General documentation
 
   about
   install
-  introduction
+  getting-started
   tutorials/index
   dataformats/index
   references

docs/references.txt

@@ -3,6 +3,8 @@
 .. _scikit-learn: http://scikit-learn.org/stable/
 .. _scipy library: http://scipy.org/scipylib/
 .. _scipy: http://scipy.org/scipylib/
+.. _Scipy Lecture Notes: http://www.scipy-lectures.org/
+.. _Practical Python for Astronomers Tutorial: http://python4astronomers.github.io/
 .. _GammaLib: http://gammalib.sourceforge.net
 .. _ctools: http://cta.irap.omp.eu/ctools
 .. _3ML: https://threeml.stanford.edu/

docs/scripts/index.rst

@@ -9,18 +9,101 @@ Command line tools  (`gammapy.scripts`)
 Introduction
 ============
 
-Currently the `gammapy.scripts` sub-package contains the Gammapy command line tools.
+Gammapy contains a bunch of command line tools,
+and we've started to add `Flask`_ web apps for cases where a GUI makes sense.
 
-This might change though ... see the notes here:
-https://github.com/gammapy/gammapy/pull/230
+Note that these are all still very much work in progress, we haven't
+settled on a very good scheme to organise the functionality, do
+argument and config handling, logging, integration with the high-level
+Sphinx docs, ...
 
-To be able to use them you have to install Gammapy:
+So please use these tools and help us make them better:
+complain if something doesn't work, file feature requests,
+... on Github or the mailing list!
+
+Overview
+========
+
+Here's a list of available tools, grouped by category.
+
+Utilities
+---------
+
+- ``gammapy-info`` calls `gammapy.scripts.info`
+- ``gammapy-test`` calls `gammapy.scripts.check` (TODO: merge with ``gammapy-info``?)
+
+Data
+----
+
+- ``gammapy-data-browse`` (web GUI tool) calls `gammapy.scripts.data_browser`
+- ``gammapy-data-manage`` calls `gammapy.scripts.data_manage`
+- ``gammapy-data-select`` calls `gammapy.scripts.data_select`
+- ``gammapy-data-show`` calls `gammapy.scripts.data_show`
+
+Spectrum
+--------
+
+- ``gammapy-spectrum`` calls `gammapy.spectrum.spectrum_analysis`
+- ``gammapy-spectrum-hspec`` calls `gammapy.hspec.run_fit` (old script, will be refactored, then removed)
+- ``gammapy-spectrum-pfsim`` calls `gammapy.script.spectrum_pfsim` (old script, will be refactored, then removed)
+- ``gammapy-spectrum-pfspec`` calls `gammapy.scripts.spectrum_pfspec` (old script, will be refactored, then removed)
+- ``gammapy-spectrum-pipe`` runs `gammapy.scripts.SpectrumPipe`
+- ``gammapy-spectrum-regions`` calls `gammapy.scripts.spectrum_regions`
+
+Image
+-----
+
+- ``gammapy-image-bin`` calls `gammapy.scripts.image_bin`
+- ``gammapy-image-coordinates`` calls `gammapy.scripts.image_coordinates`
+- ``gammapy-image-cwt`` calls `gammapy.scripts.image_cwt`
+- ``gammapy-image-derived`` calls `gammapy.scripts.image_derived`
+- ``gammapy-image-fit`` calls `gammapy.scripts.image_fit`
+- ``gammapy-image-lookup`` calls `gammapy.scripts.image_lookup`
+- ``gammapy-image-model`` calls `gammapy.scripts.image_model`
+- ``gammapy-image-model-sherpa`` calls `gammapy.scripts.image_model_sherpa`
+- ``gammapy-image_pfmap`` calls `gammapy.scripts.image_pfmap` (old script, will be refactored, then removed)
+- ``gammapy-image-pipe`` uses `gammapy.scripts.ImageAnalysis`
+- ``gammapy-image-residual`` calls `gammapy.scripts.image_residual`
+- ``gammapy-image-significance`` calls `gammapy.scripts.image_significance`
+- ``gammapy-image-ts`` calls `gammapy.scripts.image_ts`
+
+Cube
+----
+
+- ``gammapy-cube-background`` calls `gammapy.scripts.cube_background`
+- ``gammapy-cube-bin`` calls `gammapy.scripts.cube_bin`
+
+Detect
+------
+
+- ``gammapy-detect`` calls `gammapy.scripts.detect`
+- ``gammapy-detect-iterative`` calls `gammapy.scripts.detect_iterative`
+
+Catalog
+-------
+
+- ``gammapy-catalog-browse`` (web GUI tool) calls `gammapy.scripts.catalog_browser` (TODO: list in the API docs)
+- ``gammapy-catalog-query`` calls `gammapy.scripts.catalog_query`
+- ``gammapy-catalog-simulate`` calls `gammapy.scripts.catalog_simulate`
+
+
+Technical background
+====================
+
+The Gammapy command line tools and web apps use the
+`setuptools entry points <https://pythonhosted.org/setuptools/setuptools.html#automatic-script-creation>`__
+method to automatically create command line tools when Gammapy is installed.
+
+This means that to be able to use the tools you have to install Gammapy:
 
 .. code-block:: bash
 
     $ pip install --user .
 
 
+This will install the ``gammapy-*`` wrappers in a ``bin`` folder that you need to add to your ``$PATH``,
+which will then call into the appropriate function in the Gammapy package.
+
 For Gammapy development we recommend you run this command so that you can edit
 Gammapy and the tools and don't have to re-install after every change.
 
@@ -29,8 +112,19 @@ Gammapy and the tools and don't have to re-install after every change.
     $ pip install --user --editable .
 
 
+Most of the command line tools are implemented in the `gammapy.scripts` sub-package as thin wrappers
+around functionality that's implemented in the Gammapy package as re-usable functions and classes.
+In most cases all the command line tool ``main`` function does is argument passing and setting up logging.
+
+If you'd like to write your own command line tool that uses Gammapy functionality,
+you don't need to know about this or implement it in Gammapy source tree or install it into site-packages.
+Just write a ``myscript.py`` file and import the Gammapy functions, classes you need.
+
 Reference/API
 =============
 
 .. automodapi:: gammapy.scripts
     :no-inheritance-diagram:
+
+
+.. _Flask: http://flask.pocoo.org/