Add info about Gammapy contact points and gammapy-extra

CHANGES.rst

@@ -67,6 +67,7 @@ Contributors
 Pull requests
 +++++++++++++
 
+- [#435] Add info about Gammapy contact points and gammapy-extra (Christoph Deil)
 - [#421] Add spectrum fit serialisation code (Johannes King)
 - [#403] Improve spectrum analysis (Johannes King)
 - [#414] Add Windows tests on Appveyor (Christoph Deil)

Makefile

@@ -5,31 +5,45 @@ CYTHON ?= cython
 
 help:
 	@echo ''
-	@echo 'Gammapy available make targets:'
+	@echo ' Gammapy available make targets:'
 	@echo ''
-	@echo '  help             Print this help message (the default)'
+	@echo '     help             Print this help message (the default)'
 	@echo ''
-	@echo '  clean            Remove generated files'
-	@echo '  clean-repo       Remove all untracked files and directories (use with care!)'
-	@echo '  cython           Compile cython files'
+	@echo '     doc-show         Open local HTML docs in browser'
+	@echo '     clean            Remove generated files'
+	@echo '     clean-repo       Remove all untracked files and directories (use with care!)'
+	@echo '     cython           Compile cython files'
 	@echo ''
-	@echo '  trailing-spaces  Remove trailing spaces at the end of lines in *.py files'
-	@echo '  code-analysis    Run code analysis (flake8 and pylint)'
-	@echo '  flake8           Run code analysis (flake8)'
-	@echo '  pylint           Run code analysis (pylint)'
+	@echo '     trailing-spaces  Remove trailing spaces at the end of lines in *.py files'
+	@echo '     code-analysis    Run code analysis (flake8 and pylint)'
+	@echo '     flake8           Run code analysis (flake8)'
+	@echo '     pylint           Run code analysis (pylint)'
 	@echo ''
-	@echo 'Note that most things are done via `python setup.py`, we only use'
-	@echo 'make for things that are not trivial to execute via `setup.py`.'
+	@echo ' Note that most things are done via `python setup.py`, we only use'
+	@echo ' make for things that are not trivial to execute via `setup.py`.'
 	@echo ''
-	@echo 'Here'\''s some very common `setup.py` commands:'
+	@echo ' Common `setup.py` commands:'
 	@echo ''
-	@echo '  python setup.py --help-commands'
-	@echo '  python setup.py install'
-	@echo '  python setup.py develop'
-	@echo '  python setup.py test -V'
-	@echo '  python setup.py test --help # to see available options'
-	@echo '  python setup.py build_sphinx # use `-l` for clean build'
-	@echo '  open docs/_build/html/index.html'
+	@echo '     python setup.py --help-commands'
+	@echo '     python setup.py install'
+	@echo '     python setup.py develop'
+	@echo '     python setup.py test -V'
+	@echo '     python setup.py test --help # to see available options'
+	@echo '     python setup.py build_sphinx # use `-l` for clean build'
+	@echo ''
+	@echo ' More info:'
+	@echo ''
+	@echo ' * Gammapy code: https://github.com/gammapy/gammapy'
+	@echo ' * Gammapy docs: https://gammapy.readthedocs.org/'
+	@echo ''
+	@echo ' Environment:'
+	@echo ''
+	@echo '     GAMMAPY_EXTRA = $(GAMMAPY_EXTRA)'
+	@echo ''
+	@echo ' To get more info about your Gammapy installation and setup run this command'
+	@echo ' (Gammapy needs to be installed and on your PATH)'
+	@echo ''
+	@echo '     gammapy-info'
 	@echo ''
 
 clean:
@@ -60,3 +74,6 @@ pylint:
 
 # TODO: add test and code quality checks for `examples`
 # TODO: add test for IPython notebooks in gammapy-extra
+
+doc-show:
+	open docs/_build/html/index.html

docs/about.rst

@@ -29,7 +29,7 @@ Feature requests and contributions welcome!
 
 Gammapy is under very active development
 (see the `Gammapy project summary on Open HUB`_ and the `Gammapy contributors page on Github`_).
-A 1.0 release and a paper are planned for fall 2015.
+A 1.0 release and a paper are planned for 2016.
 
 For now, please see the Gammapy
 `poster <https://indico.cern.ch/event/344485/session/142/contribution/695/attachments/1136524/1626432/gammapy-icrc2015-poster.pdf>`_

docs/datasets/index.rst

@@ -1,3 +1,5 @@
+.. include:: ../references.txt
+
 .. _datasets:
 
 ************************************
@@ -23,6 +25,55 @@ The functions have a naming pattern (following the `sklearn.datasets` lead):
           And there is a separate section describing the :ref:`dataformats`
           that are commonly used in gamma-ray astronomy.
 
+.. _gammapy-extra:
+
+gammapy-extra
+=============
+
+To keep the Gammapy code repository at https://github.com/gammapy/gammapy small and clean,
+we are putting sample data files and IPython notebooks in an extra repository
+at https://github.com/gammapy/gammapy-extra/ .
+
+To get the repository, ``git clone`` it to a location of your choosing using a git protocol of your choosing
+(try HTTPS or see the `Github clone URL help article`_ if you're not sure which you want).
+
+.. code-block:: bash
+
+    git clone https://github.com/gammapy/gammapy-extra.git
+    git clone git@github.com:gammapy/gammapy-extra.git
+
+If you don't have git, you can also fetch the latest version as a zip file:
+
+.. code-block:: bash
+
+    wget https://github.com/gammapy/gammapy-extra/archive/master.zip
+    unzip master.zip # will result in a `gammapy-extra-master` folder
+
+The Gammapy tests, docs generator, examples and tutorials will access files from the ``gammapy-extra``
+repo using the `gammapy.datasets.gammapy_extra` object.
+
+For this to work, you have to set the ``GAMMAPY_EXTRA`` shell environment variable to point to that folder.
+We suggest you put this in you ``.bashrc`` or ``.profile``
+
+.. code-block:: bash
+
+    export GAMMAPY_EXTRA=/path/on/your/machine/to/gammapy-extra
+
+After you've done this, open up a new terminal (or ``source .profile``) and check if ``gammapy-extra`` is found:
+
+.. code-block:: bash
+
+    # TODO: make this print some info about gammapy-extra (including a version!!!)
+    gammapy-info
+
+Example usage:
+
+.. code-block:: python
+
+    >>> from gammapy.datasets import gammapy_extra
+    >>> gammapy_extra.filename('logo/gammapy_banner.png')
+    '/Users/deil/code/gammapy-extra/logo/gammapy_banner.png'
+
 Getting Started
 ===============
 

docs/development/howto.rst

@@ -9,6 +9,30 @@ Developer HOWTO
 This page is a collection of notes for Gammapy contributors and maintainers,
 in the form of short "How to" or "Q & A" entries.
 
+
+.. _development-contact:
+
+Contact points
+--------------
+
+If you want to talk about Gammapy, what are the options?
+
+* You can always post on the `Gammapy mailing list`_!
+  E.g. if you have an issue with Gammapy installation, analysis, a feature request or found a possible issue.
+* You can also file and issue or pull request on the `Gammapy Github page`_.
+  Making an account on Github takes only a minute and is free.
+  Github is where Gammapy development takes place, i.e. anything that might / will lead
+  to a change to the Gammapy code or documentation will eventually result in a pull request on Github.
+* Often it's unclear if some issue (e.g. an error during installation) is the result of you executing
+  the wrong command, or an actual issue in Gammapy that must be addressed by a documentation or code change.
+  In those cases we suggest you post on the mailing list first.
+* We have a `Slack`_ set up for Gammapy developer chat. You can use it via the Slack app or from your
+  web browser at `Gammapy on Slack`_. If you need help with git, Github, Python or have questions about
+  Github development (e.g. how to run tests, build the docs, ...), i.e. chat that isn't directly related
+  to an issue or pull request on Github, you can use Slack.
+* If you want to have a non-public conversation about Gammapy, or added to the Gammapy slack, please email `Christoph Deil`_.
+
+
 .. _make_clean:
 
 How to clean up old files

docs/development/index.rst

@@ -12,10 +12,12 @@ If something is not covered here, have a look at the very extensive Astropy deve
 `here <http://astropy.readthedocs.org/en/latest/#developer-documentation>`__,
 we do most things the same way.
 
-You shouldn't read all this stuff if you want to contribute something to Gammapy.
-Just open an issue or pull request on Github, or ask on the mailing list.
-We'll then help you get it done by pointing out where / how to add it and via code review on the pull request
-(and linking to relevant sections in the developer docs where relevant).
+But you don't have to read all this stuff if you want to contribute something to Gammapy.
+
+We're happy to help out with any Gammapy-related questions or issues!
+
+Just :ref:`talk to us <development-contact>`!
+
 
 .. toctree::
   :maxdepth: 1

docs/getting-started.rst

@@ -25,6 +25,24 @@ If you'd like to follow along, make sure you have Gammapy installed (see :ref:`i
 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`_.
 
+Sample datasets
+---------------
+
+The main purpose of Gammapy is to analyse gamma-ray data.
+So to do something interesting with Gammapy, you have to download or simulate some sample datasets.
+
+There's exensive information about `gammapy.datasets` in :ref:`datasets`, but for now,
+please execute the following command that will download ~ 10 MB of curated sample datasets
+that we will use for the tutorials.
+
+.. code-block:: bash
+
+    $ gammapy-data-manage --fetch-sample
+
+
+.. warning:: This isn't implemented yet, for now please fetch :ref:`gammapy-extra` !
+
+
 Using Gammapy as a Python package
 ---------------------------------
 
@@ -69,6 +87,7 @@ is available in the :ref:`spectrum_command_line_tool` section of `gammapy.spectr
 
 An example how to create an counts maps from an event list is available at TODO.
 
+
 What next?
 ----------
 

docs/references.txt

@@ -76,7 +76,8 @@
 .. _Gammapy project summary on Open HUB: https://www.openhub.net/p/gammapy
 .. _Gammapy page on PyPI: https://pypi.python.org/pypi/gammapy 
 .. _Gammapy contributors page on Github: https://github.com/gammapy/gammapy/graphs/contributors
-.. _gammapy-extra: https://github.com/gammapy/gammapy-extra
+.. _Slack: https://slack.com/
+.. _Gammapy on Slack: https://gammapy.slack.com
 
 .. _scientific Python stack: http://www.scipy.org/about.html
 
@@ -88,3 +89,4 @@
 .. _ARF: http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html#tth_sEc4
 .. _RMF: http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html#tth_sEc3.1
 
+.. _Github clone URL help article: https://help.github.com/articles/which-remote-url-should-i-use/

docs/spectrum/spectral_fitting.rst

@@ -16,7 +16,7 @@ Command line tool
 
 Spectral fitting within Gammapy is most easily performed with the ``gammapy-spectrum`` command line tool.
 The example below shows how to use ``gammapy-spectrum`` by specifying analysis
-options in a YAML config file. It assumes you have the `gammapy-extra`_
+options in a YAML config file. It assumes you have the :ref:`gammapy-extra`
 repository available.
 
 
@@ -80,7 +80,7 @@ Running a Sherpa fit
 To avoid having to deal with Sherpa directly or for scripting purposes the `~gammapy.spectrum.SpectrumFit`
 class can be used to perform a Fit as shown in the example below. It uses the PHA
 files created in the example above, so feel free to use your own files instead of
-using the ones in `gammapy-extra`_.
+using the ones in :ref:`gammapy-extra`.
 
 .. literalinclude:: run_spectrum_fit.py
     :language: python