Reorganise documentation

Jürgen Knödlseder
1 parent 228d4613
Showing 89 changed files with 105 additions and 153 deletions
doc/source/_templates/index.html
doc/source/_themes/sphinx13/layout.html
doc/source/download.rst → doc/source/admin/download.rst
doc/source/admin/index.rst
doc/source/users/user_manual/getting.rst → doc/source/admin/install.rst
doc/source/users/release_history/1.0.1.rst → doc/source/admin/release_history/1.0.1.rst
doc/source/users/release_history/1.0.rst → doc/source/admin/release_history/1.0.rst
doc/source/users/release_history/1.1.rst → doc/source/admin/release_history/1.1.rst
doc/source/users/release_history/1.2.1.rst → doc/source/admin/release_history/1.2.1.rst
doc/source/users/release_history/1.2.rst → doc/source/admin/release_history/1.2.rst
doc/source/users/release_history/1.3.rst → doc/source/admin/release_history/1.3.rst
doc/source/users/release_history/index.rst → doc/source/admin/release_history/index.rst
doc/source/conf.py
doc/source/contents.rst
doc/source/develop/index.rst
doc/source/develop/releasing/devel.rst
doc/source/users/faq.rst → doc/source/help/faq.rst
doc/source/users/help.rst → doc/source/help/index.rst
doc/source/users/issues.rst → doc/source/help/issues.rst
doc/source/users/glossary.rst
@@ -34,35 +34,4 @@ and next steps, and advance with the coding of the software. {%endtrans%}&lt;/p&gt;
 <p>{%trans%} ctools is free software distributed under the
 <a href="http://www.gnu.org/licenses/gpl.html">GNU GPL license version 3</a> {%endtrans%}</p>
  
-<h2 style="margin-bottom: 0">{%trans%}Getting started{%endtrans%}</h2>
-
-<ul>
-<li><a class="smalllink" href="{{ pathto("users/user_manual/getting") }}">{%trans%}Installation{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/user_manual/getting_started/quickstart") }}">{%trans%}Quickstart{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/user_manual/getting_started/beyond") }}">{%trans%}Beyond the first steps{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/user_manual/getting_started/python") }}">{%trans%}Using ctools from Python{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/user_manual/getting_started/models") }}">{%trans%}Modelling CTA data{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/user_manual/getting_started/response") }}">{%trans%}CTA instrument response functions{%endtrans%}</a></li>
-</ul>
-
-<h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
-
-<ul>
-<li><a class="smalllink" href="{{ pathto("users/tutorials/index") }}">{%trans%}Tutorials{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/user_manual/index") }}">{%trans%}User Manual{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/reference_manual/index") }}">{%trans%}Reference Manual{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/faq") }}">{%trans%}Frequently asked questions{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/issues") }}">{%trans%}Known issues{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/glossary") }}">{%trans%}Glossary{%endtrans%}</a></li>
-<li><a class="smalllink" href="{{ pathto("users/release_history/index") }}">{%trans%}Release history{%endtrans%}</a></li>
-<li><a class="smalllink" href="doxygen/index.html">{%trans%}Source code documentation (Doxygen){%endtrans%}</a></li>
-</ul>
-
-<h2 style="margin-bottom: 0">{%trans%}Links{%endtrans%}</h2>
-
-<ul>
-<li><a href="https://cta-gitlab.irap.omp.eu/ctools/ctools">GitLab</a></li>
-<li><a href="https://github.com/ctools/ctools">GitHub</a></li>
-<li><a href="https://cta-redmine.irap.omp.eu/projects/ctools">Redmine</a></li>
-<li><a href="https://www.openhub.net/p/ctools_">Open HUB</a>{% endblock %}</li>
-</ul>
+{% endblock %}
@@ -69,10 +69,10 @@
 <div class="pageheader">
   <ul>
     <li><a href="{{ pathto('about') }}">About</a></li>
-    <li><a href="{{ pathto('download') }}">Download</a></li>
+    <li><a href="{{ pathto('admin/index') }}">Getting ctools</a></li>
     <li><a href="{{ pathto('users/index') }}">For Users</a></li>
     <li><a href="{{ pathto('develop/index') }}">For Developers</a></li>
-    <li><a href="{{ pathto('users/help') }}">Help</a></li>
+    <li><a href="{{ pathto('help/index') }}">Help</a></li>
   </ul>
   <div>
     <a href="{{ pathto('index') }}">
-.. _download:
+.. _sec_download:
  
 Download
 ========
@@ -15,11 +15,14 @@ Releases
  
 The latest ctools release is ``ctools-1.2.1`` (30 May 2017).
  
-Below a table of ctools releases. Please note that at this stage of the
-project there is a strict link between the ctools and gammalib versions.
-Please make sure that you have the corresponding gammalib version installed
-before installing ctools. The Mac OS X packages comprise both ctools and
-gammalib.
+Below a table of ctools releases. Please read the :ref:`sec_release` to
+learn more about new features and corrected bugs in a given release.
+
+.. warning::
+   At this stage of the project there is a strict link between the ctools and
+   gammalib versions. Please make sure that you have the corresponding gammalib
+   version installed before installing ctools. The Mac OS X packages comprise
+   both ctools and gammalib.
  
 .. list-table::
    :header-rows: 1
@@ -155,7 +158,7 @@ the following command sequence (the code will be installed into the
    $ export CTOOLS=/usr/local/gamma
    $ source $CTOOLS/bin/ctools-init.sh
  
-Please read the :ref:`sec_getting` section if you need more information on
+Please read the :ref:`sec_install` section if you need more information on
 how to install ctools.
  
 .. note::
+.. _sec_admin:
+
+Getting ctools
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   download
+   install
+   release_history/index
-.. _sec_getting:
+.. _sec_install:
  
-Getting the ctools
-==================
+Installing ctools
+=================
  
 Before you start
 ----------------
@@ -58,7 +58,7 @@ You will need the following to build the GammaLib:
 Furthermore it is recommended to have readline and ncurses installed
 (including the developer packages).
  
-After downloading the GammaLib tarball (see :ref:`download`), save it
+After downloading the GammaLib tarball (see :ref:`sec_download`), save it
 in an appropriate location (for example ``$HOME/builds``), and type
  
 .. code-block:: bash
@@ -130,7 +130,7 @@ If you use C shell or a variant then add the following to your
 Building ctools
 ---------------
  
-After downloading the ctools tarball (see :ref:`download`), save it in 
+After downloading the ctools tarball (see :ref:`sec_download`), save it in 
 an appropriate location (for example ``$HOME/builds``), and type
  
 .. code-block:: bash
-.. _release:
+.. _sec_release:
  
 Release History
 ===============
@@ -59,7 +59,7 @@ master_doc = &#39;contents&#39;
  
 # General information about the project.
 project = u'ctools'
-copyright = u'2014-2016, ctools developers'
+copyright = u'2014-2017, ctools developers'
  
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
+.. _sec_contents:
+
 Documentation
 =============
  
@@ -5,7 +7,7 @@ Documentation
    :maxdepth: 1
  
    about
-   download
+   admin/index
    users/index
    develop/index
-   users/help
+   help/index
-.. _develop:
+.. _sec_develop:
  
 Developer documentation
 =======================
@@ -39,6 +39,14 @@ Below some reasources to learn how to contribute to ctools:
    profiling/index
    releasing/index
  
+Links:
+
+* `GitLab <https://cta-gitlab.irap.omp.eu/ctools/ctools>`_
+* `GitHub <https://github.com/ctools/ctools>`_
+* `Redmine <https://cta-redmine.irap.omp.eu/projects/ctools>`_
+* `Open HUB <https://www.openhub.net/p/ctools_>`_
+* `Source code documentation (Doxygen) <doxygen/index.html>`_
+
 And here some status shields:
  
 .. image:: https://cta-jenkins.irap.omp.eu/buildStatus/icon?job=ctools-integrate-os
-.. _dev_releasing_merge:
+.. _dev_releasing_devel:
  
 Incrementing the development version
 ====================================
@@ -77,7 +77,7 @@ asked.
  
   The GammaLib interface is still not fully stabilised, hence ctools is
   continuously adapted to match the interface evolution
-  (see the :ref:`download` section for a correspondance of versions).
+  (see the :ref:`sec_download` section for a correspondance of versions).
   We plan however to put the GammaLib interface under change control.
   ctools should then become more independent from GammaLib.
  
-.. _help:
+.. _sec_help:
  
 Getting Help
 ============
  
-If you need help you should first check the
-:ref:`Frequently Asked Questions <faq>` and the list of
-:ref:`Known Issues <issues>`.
+If you need help you should first check
+
+.. toctree::
+   :maxdepth: 1
+
+   faq
+   issues
+
 In case that you do not find an answer to your question you may post your 
 question on the ctools@irap.omp.eu mailing list.
 To subscribe to this list you simply need to send an e-mail to
@@ -43,4 +48,4 @@ Also explain the motivation for your request and provide some hint on how
 urgently you need the new feature.
  
 You may click on ``Watch`` in the top-right corner of the issue page to make sure
-that you will receive an e-mail notification when the issue is updated.
 \ No newline at end of file
+that you will receive an e-mail notification when the issue is updated.
+.. _sec_glossary:
+
 Glossary
 ========
  
-.. _users:
+.. _sec_users:
  
 User Documentation
 ==================
@@ -9,8 +9,4 @@ User Documentation
    tutorials/index
    user_manual/index
    reference_manual/index
-   faq
-   issues
    glossary
-   release_history/index
-   help
@@ -24,7 +24,7 @@ After downloading, configure GammaLib and ctools as follows:
    $ export CTOOLS=/usr/local/gamma
    $ source $CTOOLS/bin/ctools-init.sh
  
-Have a look at :ref:`getting the ctools <sec_getting>` if you need more
+Have a look at :ref:`getting the ctools <sec_install>` if you need more
 information about the installation and configuration process.
  
 .. note::
@@ -11,5 +11,4 @@ First CTA Data Challenge
    getting_data
    data_organisation
    first
-   howto
  
@@ -49,7 +49,7 @@ The :ref:`csresmap` script is then used as follows:
   Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT) [SUBDIV] 
  
 In our example, the map will cover a field of 4° x 4° centred on the
-Crab nebula at a pixel scale of 0.02° per pixel.
+Crab nebula at a pixel scale of 0.02 degrees per pixel.
 The resulting residual map ``resmap.fits``, smoothed with a Gaussian
 kernel of 3 pixels to enhance features, is shown in the following figure.
 Obviously, the map is free from any significant residuals.
-.. _beyond:
+.. _sec_beyond:
  
 Beyond the first steps
 ----------------------
@@ -11,7 +11,7 @@ And you should be ready for doing your own cutting edge CTA science data
 analyses.
  
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
  
    beyond_combine
    beyond_stacked
@@ -39,7 +39,7 @@ The :ref:`cttsmap` tool creates a FITS file containing for each pixel the
 Test Statistic value as well as the fit parameters for the test source.
 The figure below shows the resulting Test Statistic map.
  
-.. figure:: first_tsmap.png
+.. figure:: howto_tsmap.png
    :width: 400px
    :align: center
  
@@ -3,8 +3,11 @@
 Analysis cookbook
 =================
  
-The following sections explain how you can address some specific analysis
-issues.
+The following sections teach you how to use ctools to address some typical
+science analysis. The sections provide examples that are based on the data
+distributed within the CTA Consortium for the
+:ref:`first CTA Data Challenge <glossary_1dc>`.
+These examples can be easily adapted to any data you have at your disposal.
  
 .. toctree::
    :maxdepth: 1
@@ -18,17 +21,4 @@ issues.
    howto_lightcurve
    howto_phasecurve
    howto_exclude
-   howto_vo
-
-If you cannot find the answer to your question, have a look at the
-:ref:`first steps with ctools <quickstart>`
-and the
-:ref:`beyond the first steps <beyond>`
-sections of the User Manual. You may also consult the
-:ref:`Reference Manual <reference>`
-as well as the
-:ref:`frequently asked questions <faq>`.
-If after this you still need some help, please create a
-`support ticket <https://cta-redmine.irap.omp.eu/projects/ctools/issues/new>`_.
-Specify ``Support`` as Tracker, choose a short and meaningful subject,
-and add an exhaustive description of your request.
+   howto_vo
 \ No newline at end of file
-.. _sec_analysis:
+.. _sec_iact_analysis:
  
 Analysing IACT data
 ===================
  
 In order to analyse data from current IACTs, you first have to retrieve the
-data. Information on how to do that can be found in the section :ref:`sec_copy`.
+data. Information on how to do that can be found in the section :ref:`sec_iact_copy`.
  
 Check available FITS production
 -------------------------------
@@ -174,7 +174,7 @@ Alternatively, you can merged models using the :ref:`csmodelmerge` script:
 A list of available sky models can be found
 `here <http://gammalib.sourceforge.net/user_manual/modules/model.html>`_.
 If you are not familiar with creating sky models you should read the section
-about :ref:`modelling CTA data <models>`.
+about :ref:`modelling CTA data <sec_models>`.
  
  
 Example XML files
-.. _sec_copy:
+.. _sec_iact_copy:
  
 Copying IACT data
 ==================
-.. _sec_high_level:
+.. _sec_iact_high_level:
  
 High level analysis tools for IACT data
 =======================================
@@ -291,7 +291,7 @@ value is added to the output file. For instance a map of the prefactor can be vi
   $ ds9 tsmap.fits[Prefactor] 
  
 Since :ref:`cttsmap` has to run a parameter optimisation in each skymap bin, it is very time comsuming to
-compute a fine-granulated TS sky map. Read here how to split up the :ref:`computation into several jobs <sec_tips>`. 
+compute a fine-granulated TS sky map. Read here how to split up the :ref:`computation into several jobs <sec_iact_tips>`. 
 Similar as many other tools :ref:`cttsmap` can also work on binned observation input:
  
 .. code-block:: bash
+.. _sec_iact:
+
 Analysing current IACT data
 ===========================
  
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
  
    copy
    analysis
-.. _sec_simulation:
+.. _sec_iact_simulation:
  
 Simulating IACT data
 ====================
@@ -10,7 +10,7 @@ Simulations for a specific observation container
 ------------------------------------------------
 On default, :ref:`ctobssim` builds a new observation container by querying relevant user parameters. In case
 an observation XML container is already in place, the hidden parameter ``inobs`` can be specified (:ref:`see here how to create an
-observation container <sec_analysis>`). It might be useful to run :ref:`ctselect` beforehand to ensure that the simulation knows about
+observation container <sec_iact_analysis>`). It might be useful to run :ref:`ctselect` beforehand to ensure that the simulation knows about
 energy thresholds, field of view, etc. If an unselected observation container is used, the simulation tool will query for global energy
 boundaries and a global RoI radius. The following example illustrates the usage of an already selected observation container.
  
@@ -59,7 +59,7 @@ observations with at a certain zenith angle range (20-25 degrees) and azimuth an
 	Runlist outfile [zen20_az90.lis]
  
 Of course, further details could be specified, e.g. one might want to check for a certain range of muon efficieny, or any other parameter which impacts IRFs.
-The output runlist subsequently has to be converted to an observation XML file using :ref:`csiactobs` (:ref:`see here how to execute this tool <sec_analysis>`).
+The output runlist subsequently has to be converted to an observation XML file using :ref:`csiactobs` (:ref:`see here how to execute this tool <sec_iact_analysis>`).
 In the following it is assumed that the observation XML file of the selected representative observations is produced and called ``myobs.xml``.
  
 Create caldb entry
-.. _sec_tips:
+.. _sec_iact_tips:
  
 Tips, Tricks and FAQs
 =====================
@@ -260,7 +260,7 @@ parameter:
 Compute flux maps
 -----------------
 The creation of a flux map is much more expensive in terms of computing than an
-excess map. In the section about :ref:`high level analysis tools <sec_high_level>`,
+excess map. In the section about :ref:`high level analysis tools <sec_iact_high_level>`,
 the usage of :ref:`cttsmap` was demonstrated. This tool can also be used to
 generate flux maps. For this, the user has to incorporate a test source in the
 XML model file. This source should consist of a spectral component using a
@@ -500,4 +500,4 @@ script and for example ds9:
  
    $ python $CTOOLS/examples/show_spectrum.py spectrum.fits
    $ ds9 excessmap.fits
-  
 \ No newline at end of file
+  
@@ -6,4 +6,8 @@ Tutorials
 .. toctree::
    :maxdepth: 1
  
+   quickstart/index
+   beyond/index
+   howto/index
    1dc/index
+   iact_analysis/index
 \ No newline at end of file
@@ -15,7 +15,7 @@ fitted spectral model. And you will learn how to take energy dispersion
 into account.
  
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
  
    simulating
    binning
-Getting started
-===============
+.. _sec_using:
+
+Using ctools
+============
  
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
  
-   quickstart
-   beyond
+   python
    models
    response
-   python
  
-.. _models:
+.. _sec_models:
  
 Modelling CTA data
 ------------------
@@ -14,7 +14,7 @@ Generally, the measured events can be separated into two distinct classes:
 events being attributed to gamma rays of celestial origin (the "source" 
 events) or events being attributed to any other kind of trigger (the 
 "background" events).
-In the first case, the :ref:`Instrument Response Functions (IRFs) <response>`
+In the first case, the :ref:`Instrument Response Functions (IRFs) <sec_response>`
 describe how an incident gamma-ray converts into a measured event.
 In the second case there is often no general prescription, and the 
 distribution of background events is commonly modeled directly in the data 
@@ -33,10 +33,10 @@ Model components are generally parametric, and model parameters can be
 adjusted through a maximum likelihood procedure to find the set of 
 parameters that represent best the measured data.
 Model components representing celestial sources are convolved with the 
-:ref:`IRFs <response>` to predict the expected number of source events in 
+:ref:`IRFs <sec_response>` to predict the expected number of source events in 
 the data.
 Background model components will be directly expressed as expected number 
-of background events without any :ref:`IRF <response>` convolution.
+of background events without any :ref:`IRF <sec_response>` convolution.
  
  
 .. _sec_model_implementation:
-.. _python:
+.. _sec_python:
  
 Using ctools from Python
 ------------------------
-.. _response:
+.. _sec_response:
  
 CTA Instrument Response Functions
 ---------------------------------
-Glossary
-========
-
--  **GammaLib** (`<http://cta.irap.omp.eu/gammalib/>`_)
-
-   A versatile toolbox for scientific analysis of astronomical
-   gamma-ray data.
-
--  **cfitsio** (`<http://heasarc.gsfc.nasa.gov/fitsio/>`_)
-
-   Library of C and Fortran subroutines for reading and writing data
-   files in FITS data format.
-
--  **FITS** (`<http://fits.gsfc.nasa.gov/>`_)
-
-   Flexible Image Transport System.
-
--  **FTOOLS** (`<http://heasarc.gsfc.nasa.gov/ftools/>`_)
-
-   Collection of utility programs to create, examine, or modify data
-   files in the FITS data format.
-
--  **GNU** (`<http://www.gnu.org/>`_)
-
-   A free Unix-like operating system.
-
--  **HEASARC** (`<http://heasarc.gsfc.nasa.gov/>`_)
-
-   High Energy Astrophysics Science Archive Research Centre.
-
--  **Python** (`<http://www.python.org/>`_)
-
-   Dynamic programming language that is used in a wide variety of
-   application domains.
-
@@ -3,12 +3,9 @@ User Manual
 ===========
  
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
  
    introduction
-   getting
    getting_started/index
-   iact_analysis/index
    plotting
-   glossary
  
@@ -55,7 +55,6 @@ command line or used as Python classes, as illustrated below:
  
 In this User Manual you will now learn how to install and use the ctools
 package.
-If you encounter any problems, please read the :ref:`faq` and :ref:`issues`
-sections. If you're desperate, you may need :ref:`help`.
-And you should read the :ref:`develop` section if you would like to 
+If you encounter any problems, please read the :ref:`sec_help` section.
+And you should read the :ref:`sec_develop` section if you would like to
 contribute to the ctools developments.