From e36f3da251a683ecfd8ec68317b5fbc2b9e4ee68 Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Sun, 13 Dec 2015 00:39:06 +0100 Subject: [PATCH] Update GammaLib user documentation. --- doc/source/coding/design.rst | 20 ++++++++++++-------- doc/source/coding/rules.rst | 6 +----- doc/source/download.rst | 5 +++-- doc/source/installation.rst | 20 ++++++++++---------- doc/source/user_manual/getting.rst | 6 +++--- doc/source/user_manual/index.rst | 1 - doc/source/user_manual/introduction.rst | 2 +- doc/source/user_manual/modules/support.rst | 44 ++++++++++++++++++++++++++++++++++++++++++-- doc/source/user_manual/modules/uml_support.png | Bin 47450 -> 0 bytes doc/source/user_manual/quickstart.rst | 25 ------------------------- 10 files changed, 72 insertions(+), 57 deletions(-) delete mode 100644 doc/source/user_manual/quickstart.rst diff --git a/doc/source/coding/design.rst b/doc/source/coding/design.rst index f865928..498bc6f 100644 --- a/doc/source/coding/design.rst +++ b/doc/source/coding/design.rst @@ -18,9 +18,11 @@ file: #include #endif -Note that **the ``config.h`` file should not be included in header files**, -since header files are used by the outside world without any knowledge -about ``config.h``. +.. warning:: + + **The config.h file should never be included in header files.** + The header files are used by the outside world without any knowledge + about ``config.h``. One of the most commonly used configuration options used throughout GammaLib is related to range checking. Range checks are usually @@ -305,11 +307,13 @@ following guidelines should be respected as far as possible: - Avoid as far as possible methods that are only defined in the derived class. -Also note that **for a derived class, ``init_members()``, -``copy_members(const &A a)`` and ``free_members()`` should only act on derived -class members but not on base class members**. Any exception from this -rule needs very careful documentation since it can easily be the source -of memory leaks. +.. warning:: + + **For a derived class, init_members(), copy_members(const &A a) and + free_members() should only act on derived class members but not on base + class members**. Any exception to this rule needs very careful + documentation since it can easily be the source of memory leaks. + Method naming conventions ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/coding/rules.rst b/doc/source/coding/rules.rst index 19537e3..a410f7b 100644 --- a/doc/source/coding/rules.rst +++ b/doc/source/coding/rules.rst @@ -8,7 +8,7 @@ C++ rules --------- All GammaLib C++ code must be compatible with ISO standard C++98. -Do not use C++11 features. +Do not use C++11 features (see `here `__ if you don't know what C++98 and C++11 is and note that C++03 is just a minor correction of C++98). @@ -189,16 +189,12 @@ Code semantics >>> import gammalib >>> energy = gammalib.GEnergy(10, 'TeV') - >>> import numpy as np - >>> import matplotlib.pyplot as plt In interactive sessions (`IPython `_ is recommended) to save typing you can use ``import *`` to import everything into your local namespace:: >>> from gammalib import * >>> energy = GEnergy(10, 'TeV') - >>> from numpy import * - >>> from matplotlib.pyplot import * Using ``import *`` in Python scripts is not recommended. Some reason are given in `this section `__ diff --git a/doc/source/download.rst b/doc/source/download.rst index 5ebb803..4114845 100644 --- a/doc/source/download.rst +++ b/doc/source/download.rst @@ -14,10 +14,11 @@ Releases -------- The latest GammaLib release is -`gammalib-0.11.0 `_ -(1 November 2015). +`gammalib-1.0.0 `_ +(12 December 2015). To download an older release, click on the corresponding release number: +`0.11.0 `_ `0.10.0 `_ `0.9.1 `_ `0.9.0 `_ diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 938b59c..5274b41 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -5,8 +5,8 @@ Installation .. note :: - These installation instructions apply to gammalib-0.11.0 and - later. gammalib-0.11.0 has been built, installed and tested + These installation instructions apply to gammalib-1.0.0 and + later. gammalib-1.0.0 has been built, installed and tested successfully on Debian, Ubuntu, Mandriva, OpenSUSE, Scientific Linux, CentOS, Mac OS X, FreeBSD, and OpenSolaris (using gcc), so hopefully it also installs on your distribution. In case you encounter @@ -51,7 +51,7 @@ shared library by typing :: GammaLib can also benefit from the presence of the readline library that provides line-editing and history capabilities for text input (GammaLib -offers however also full functionality without having readline +offers however full functionality without having readline installed). readline (which depends on ncurses) is available on most system as a prebuilt library, so also here we recommend to use your package manager to install the libraries if they are not already there. @@ -83,7 +83,7 @@ Building GammaLib If you need the latest source code from the git repository that has not yet been released you may also clone the gammalib git repository using :: - $ git clone https://cta-git.irap.omp.eu/gammalib + $ git clone https://cta-gitlab.irap.omp.eu/gammalib/gammalib.git In case you encounter an SSL certificat problem, type :: @@ -95,7 +95,7 @@ Building GammaLib $ git checkout devel $ ./autogen.sh - This will make sure that you use the validated development trunk and + This will make sure that you use the development trunk. It also creates the configuration file that is needed to configure GammaLib before compilation. Continue then with the procedure below starting with ``./configure``. @@ -122,19 +122,19 @@ source files and builds the C++ library and Python module. Type ``./configure`` and not simply ``configure`` to ensure that the configuration script in the current directory is used and not some other system-wide configuration script. By default, the install directory is set to -``/usr/local/gamma``. To change the install directory an optional -``--prefix`` argument should be given, for example :: +``/usr/local/gamma``. To change the install directory, provide an optional +``--prefix`` argument, for example :: $ ./configure --prefix=/usr/local If cfitsio and/or readline is not installed in a standard location for -libraries (such as ``/usr/lib`` or ``/usr/local/lib``), the appropriate -location(s) can be specified using the ``LDFLAGS`` (for the library +libraries (such as ``/usr/lib`` or ``/usr/local/lib``), you can specify +the appropriate location(s) using the ``LDFLAGS`` (for the library directory) and ``CPPFLAGS`` (for the include directory) options:: $ ./configure LDFLAGS='-L/opt/local/lib' CPPFLAGS='-I/opt/local/include' -A full list of configuration options can be found using :: +You can find a full list of configuration options using :: $ ./configure --help diff --git a/doc/source/user_manual/getting.rst b/doc/source/user_manual/getting.rst index 0c1d7a4..0044435 100644 --- a/doc/source/user_manual/getting.rst +++ b/doc/source/user_manual/getting.rst @@ -148,15 +148,15 @@ from this site by selection the gammalib package from the table. Alternatively, the code can be downloaded and unpacked from the UNIX prompt using:: - $ wget --no-check-certificate http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz - $ tar xfz gammalib-0.11.0.tar.gz + $ wget --no-check-certificate http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-1.0.0.tar.gz + $ tar xfz gammalib-1.0.0.tar.gz The GammaLib source code can also be cloned using git. This method is recommended if you plan to contribute to the development of the GammaLib library. Assuming that git is installed on your system, you may clone GammaLib using:: - $ git clone https://cta-git.irap.omp.eu/gammalib + $ git clone https://cta-gitlab.irap.omp.eu/gammalib/gammalib.git In case that you get: diff --git a/doc/source/user_manual/index.rst b/doc/source/user_manual/index.rst index 4d53c27..2b3a9f4 100644 --- a/doc/source/user_manual/index.rst +++ b/doc/source/user_manual/index.rst @@ -7,7 +7,6 @@ User Manual introduction getting - quickstart modules/index internals manual/index diff --git a/doc/source/user_manual/introduction.rst b/doc/source/user_manual/introduction.rst index f4cf922..a5823c8 100644 --- a/doc/source/user_manual/introduction.rst +++ b/doc/source/user_manual/introduction.rst @@ -43,7 +43,7 @@ are: * Issue tracker: https://cta-redmine.irap.omp.eu/projects/gammalib/issues * Documentation: http://cta.irap.omp.eu/gammalib/ -The present document applies to GammaLib version 0.11. +The present document applies to GammaLib version 1.0. GammaLib is designed to compile on any POSIX compliant platform. So far, GammaLib has been successfully compiled and tested on Mac OS X, OpenBSD, OpenSolaris diff --git a/doc/source/user_manual/modules/support.rst b/doc/source/user_manual/modules/support.rst index 8e9d358..39008da 100644 --- a/doc/source/user_manual/modules/support.rst +++ b/doc/source/user_manual/modules/support.rst @@ -38,10 +38,17 @@ and a string storage, respectively. As most of the classes are unrelated, they will be described individually in the following sections. -Column Separated Value tables +Bilinear interpolation +~~~~~~~~~~~~~~~~~~~~~~ + +The :doxy:`GBilinear` class handles bilinear interpolation of values in a +two-dimensional table. + + +Comma-Separated Value tables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :doxy:`GCsv` class handles column separated value tables. Column separated +The :doxy:`GCsv` class handles comma-separated value tables. Comma-separated value tables are ASCII files representing a table, where individual table columns a separated by a specific character (for example a whitespace or a comma). @@ -113,6 +120,37 @@ Runtime exceptions Usage =============================== ===== +Filename handling +~~~~~~~~~~~~~~~~~ + +The :doxy:`GFilename` class handles file names in GammaLib, including +extensions for FITS files in the cfitsio format. The following file name +formats are supported :: + + myfile.fits + myfile.fits[EVENTS] + myfile.fits[EVENTS,2] + myfile.fits[3,2] + +The class decomposes the input string into the filename and the extension. +The filename can be access using the :doxy:`GFilename::filename` +method, the extension name using the :doxy:`GFilename::extname` method, +the extension number using the :doxy:`GFilename::extno` method and the +extension version using the :doxy:`GFilename::extver` method. The latter +three methods take an argument that specifies the default value that +should be used in case that no extension information is specified. Below +a usage example that extracts by default the ``EBOUNDS`` table from a +FITS file: + +.. code-block:: cpp + :linenos: + + GFits file; + GFilename fname(filename); + file.open(fname.filename()); + const GFitsTable& table = *file.table(fname.extname("EBOUNDS")); + + Linear interpolation ~~~~~~~~~~~~~~~~~~~~ @@ -279,9 +317,11 @@ Function Description ``gammalib::plaw_energy_flux`` Compute energy flux under a power law. ``gammalib::elogmean`` Computes geometric mean of energy. ``gammalib::file_exists`` Check whether a file exists. +``gammalib::file_exists_gzip`` Check whether a file (or a gzipped version of it) exists. ``gammalib::dir_exists`` Check whether a directory exists. ``gammalib::is_infinite`` Check whether a double precision value is infinite. ``gammalib::is_notanumber`` Check whether a double precision value is not a number. +``gammalib::is_fits`` Check whether a file is a FITS file. ``gammalib::contains`` Check whether a string contains a sub-string. ``gammalib::warning`` Dump warning in console. ``gammalib::xml2str`` Converts XML to string. diff --git a/doc/source/user_manual/modules/uml_support.png b/doc/source/user_manual/modules/uml_support.png index 8c6faa6..b992b84 100644 Binary files a/doc/source/user_manual/modules/uml_support.png and b/doc/source/user_manual/modules/uml_support.png differ diff --git a/doc/source/user_manual/quickstart.rst b/doc/source/user_manual/quickstart.rst deleted file mode 100644 index 7def1ec..0000000 --- a/doc/source/user_manual/quickstart.rst +++ /dev/null @@ -1,25 +0,0 @@ -Getting started with GammaLib -============================= - -A quick GammaLib tutorial -------------------------- - -To be written ... - - -Using GammaLib from Python --------------------------- - -To be written ... - - -Programming guidelines ----------------------- - -To be written ... - - -Frequently asked questions --------------------------- - -To be written ... -- libgit2 0.21.4