Reorder code in documentation (first C++, then Python)

Jürgen Knödlseder
1 parent 381fb883
Showing 7 changed files with 126 additions and 137 deletions
doc/source/users/user_manual/modules/fits/create.rst
doc/source/users/user_manual/modules/obs/caldb.rst
doc/source/users/user_manual/modules/obs/energy.rst
doc/source/users/user_manual/modules/obs/xml.rst
doc/source/users/user_manual/modules/support/interpolation.rst
doc/source/users/user_manual/modules/support/media.rst
doc/source/users/user_manual/modules/support/random.rst
@@ -6,27 +6,6 @@ one image and one table (see ``examples/cpp/createfits/createfits.cpp`` for the
 source code; the line numbers are for reference and are not part of
 the source code)
-**Python**
-
-.. code-block:: python
-   :linenos:
-
-   fits  = gammalib.GFits()
-   image = gammalib.GFitsImageDouble(20,10)
-   for x in range(20):
-       for y in range(10):
-           image[x,y] = x+100.0*y
-   fits.append(image)
-   table  = gammalib.GFitsBinTable()
-   column = gammalib.GFitsTableDoubleCol('ENERGY', 10, 3)
-   for row in range(10):
-       for index in range(3):
-           column[row, index] = row*100.0+index
-   table.append(column)
-   fits.append(table)
-   fits.saveto('my_fits_file.fits', True)
-   fits.close()
-
 **C++**
 .. code-block:: cpp
@@ -52,6 +31,27 @@ the source code)
    fits.saveto("my_fits_file.fits", true);
    fits.close();
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   fits  = gammalib.GFits()
+   image = gammalib.GFitsImageDouble(20,10)
+   for x in range(20):
+       for y in range(10):
+           image[x,y] = x+100.0*y
+   fits.append(image)
+   table  = gammalib.GFitsBinTable()
+   column = gammalib.GFitsTableDoubleCol('ENERGY', 10, 3)
+   for row in range(10):
+       for index in range(3):
+           column[row, index] = row*100.0+index
+   table.append(column)
+   fits.append(table)
+   fits.saveto('my_fits_file.fits', True)
+   fits.close()
+
 In line 1, a FITS object is allocated in memory.
 An image is created in line 2, comprising 20 pixels in the x-direction
 and 10 pixels in the y-direction, each pixel being a double precision
@@ -11,37 +11,28 @@ The database is the open by specifying a mission and an instrument name.
 The examples below show two variants of opening the ``prod2`` database for
 ``CTA``.
-**Python**
-
-.. code-block:: python
-   :linenos:
-
-   import gammalib                                      # Make GammaLib available
-   caldb1 = gammalib.GCaldb('cta','prod2')              # Using opening constructor
-   caldb2 = gammalib.GCaldb()
-   caldb2.open('cta','prod2')                           # Using open method
-
 **C++**
 .. code-block:: cpp
    :linenos:
-   #include "GammaLib.hpp"                              // Make GammaLib available
    GCaldb caldb1("cta","prod2");                        // Using opening constructor
    GCaldb caldb2;
    caldb2.open("cta","prod2");                          // Using open method
-Once opened, the database can be used to locate for example the filename
-of a response component. The examples below show how the effective area
-filename for the response ``South_5h`` is accessed via the calibration
-database.
-
 **Python**
 .. code-block:: python
    :linenos:
-   filename = caldb1.filename('','','EFF_AREA','','','NAME(South_5h)')
+   caldb1 = gammalib.GCaldb('cta','prod2')              # Using opening constructor
+   caldb2 = gammalib.GCaldb()
+   caldb2.open('cta','prod2')                           # Using open method
+
+Once opened, the database can be used to locate for example the filename
+of a response component. The examples below show how the effective area
+filename for the response ``South_5h`` is accessed via the calibration
+database.
 **C++**
@@ -49,3 +40,10 @@ database.
    :linenos:
    GFilename filename = caldb1.filename("","","EFF_AREA","","","NAME(South_5h)");
+
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   filename = caldb1.filename('','','EFF_AREA','','','NAME(South_5h)')
@@ -12,30 +12,28 @@ The code threads below illustrate how an energy of 511 keV can be set using
 the energy constructor or a dedicated method, and how that energy can be
 retrieved in units of MeV.
-**Python**
-
-.. code-block:: python
-   :linenos:
-
-   import gammalib                                      # Make GammaLib available
-   energy1 = gammalib.GEnergy(511.0,'keV')              # Using energy constructor
-   energy2 = gammalib.GEnergy()
-   energy2.keV(511.0)                                   # Using keV method
-   E_MeV1 = energy2('MeV')                              # Get energy in MeV
-   E_MeV2 = energy2.MeV()                               # Another variant to get energy in MeV
-
 **C++**
 .. code-block:: cpp
    :linenos:
-   #include "GammaLib.hpp"                              // Make GammaLib available
    GEnergy energy1(511.0,"keV");                        // Using energy constructor
    GEnergy energy2;
    energy2.keV(511.0);                                  // Using keV method
    double E_MeV1 = energy2("MeV");                      // Get energy in MeV
    double E_MeV2 = energy2.MeV();                       // Another variant to get energy in MeV
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   energy1 = gammalib.GEnergy(511.0,'keV')              # Using energy constructor
+   energy2 = gammalib.GEnergy()
+   energy2.keV(511.0)                                   # Using keV method
+   E_MeV1 = energy2('MeV')                              # Get energy in MeV
+   E_MeV2 = energy2.MeV()                               # Another variant to get energy in MeV
+
 Energies can be added and subtracted, or multiplied or divided by a floating
 point value.
 In addition, two energies can be divided, resulting in a floating point value.
@@ -45,30 +43,28 @@ Energies can be collected by the :doxy:`GEnergies` container class. The threads
 below illustrate how energies can be appended or inserted into the
 :doxy:`GEnergies` container class.
-**Python**
-
-.. code-block:: python
-   :linenos:
-
-   import gammalib                                      # Make GammaLib available
-   energy1  = gammalib.GEnergy(511.0,'keV')             # Set first energy
-   energy2  = gammalib.GEnergy(1024.0,'keV')            # Set second energy
-   energies = gammalib.GEnergies()                      # Create energy container instance
-   energies.append(energy1)                             # Append first energy
-   energies.insert(0,energy2)                           # Insert second energy before first energy
-
 **C++**
 .. code-block:: cpp
    :linenos:
-   #include "GammaLib.hpp"                              // Make GammaLib available
    GEnergy   energy1(511.0,"keV");                      // Set first energy
    GEnergy   energy2(1024.0,"keV");                     // Set second energy
    GEnergies energies;                                  // Create energy container instance
    energies.append(energy1);                            // Append first energy
    energies.insert(0,energy2);                          // Insert second energy before first energy
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   energy1  = gammalib.GEnergy(511.0,'keV')             # Set first energy
+   energy2  = gammalib.GEnergy(1024.0,'keV')            # Set second energy
+   energies = gammalib.GEnergies()                      # Create energy container instance
+   energies.append(energy1)                             # Append first energy
+   energies.insert(0,energy2)                           # Insert second energy before first energy
+
 The energy container can be saved into a file using the :doxy:`GEnergies::save()`
 method, and loaded from a file using either the load constructor or the
 :doxy:`GEnergies::load()` method.
@@ -58,47 +58,17 @@ Similar definitions exist for the other instruments.
 The code threads below show different variants of how observations can be
 loaded from or saved into an XML file.
-**Python**
-
-.. code-block:: python
-   :linenos:
-
-   import gammalib                                      # Make GammaLib available
-   obs = gammalib.GObservations('my_observations.xml')  # Construct observations from XML file
-   obs.save('my_copied_observations.xml')               # Save observations into XML file
-
-.. code-block:: python
-   :linenos:
-
-   import gammalib                                      # Make GammaLib available
-   obs = gammalib.GObservations()                       # Construct empty observations
-   obs.load('my_observations.xml')                      # Load observations from XML file
-   obs.save('my_copied_observations.xml')               # Save observations into XML file
-
-.. code-block:: python
-   :linenos:
-
-   import gammalib                                      # Make GammaLib available
-   obs    = gammalib.GObservations()                    # Construct empty observations
-   xmlin  = gammalib.GXml('my_observations.xml')        # Construct GXml instance from XML file
-   xmlout = gammalib.GXml()                             # Construct empty GXml instance
-   obs.read(xmlin)                                      # Read observations from GXml instance
-   obs.write(xmlout)                                    # Write observations into GXml instance
-   xmlout.save('my_copied_observations.xml')            # Save GXml instance in XML file
-
 **C++**
 .. code-block:: cpp
    :linenos:
-   #include "GammaLib.hpp"                                  // Make GammaLib available
    GObservations obs("my_observations.xml");                // Construct observations from XML file
    obs.save("my_copied_observations.xml");                  // Save observations into XML file
 .. code-block:: cpp
    :linenos:
-   #include "GammaLib.hpp"                                  // Make GammaLib available
    GObservations obs;                                       // Construct empty observations
    obs.load("my_observations.xml");                         // Load observations from XML file
    obs.save("my_copied_observations.xml");                  // Save observations into XML file
@@ -106,10 +76,34 @@ loaded from or saved into an XML file.
 .. code-block:: cpp
    :linenos:
-   #include "GammaLib.hpp"                                  // Make GammaLib available
    GObservations obs;                                       // Construct empty observations
    GXml          xmlin("my_observations.xml");              // Construct GXml instance from XML file
    GXml          xmlout;                                    // Construct empty GXml instance
    obs.read(xmlin);                                         // Read observations from GXml instance
    obs.write(xmlout);                                       // Write observations into GXml instance
    xmlout.save("my_copied_observations.xml");               // Save GXml instance in XML file
+
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   obs = gammalib.GObservations('my_observations.xml')  # Construct observations from XML file
+   obs.save('my_copied_observations.xml')               # Save observations into XML file
+
+.. code-block:: python
+   :linenos:
+
+   obs = gammalib.GObservations()                       # Construct empty observations
+   obs.load('my_observations.xml')                      # Load observations from XML file
+   obs.save('my_copied_observations.xml')               # Save observations into XML file
+
+.. code-block:: python
+   :linenos:
+
+   obs    = gammalib.GObservations()                    # Construct empty observations
+   xmlin  = gammalib.GXml('my_observations.xml')        # Construct GXml instance from XML file
+   xmlout = gammalib.GXml()                             # Construct empty GXml instance
+   obs.read(xmlin)                                      # Read observations from GXml instance
+   obs.write(xmlout)                                    # Write observations into GXml instance
+   xmlout.save('my_copied_observations.xml')            # Save GXml instance in XML file
@@ -7,19 +7,6 @@ used to describe a functional relation :math:`y_i=f(x_i)`. The following
 code illustrates how the :doxy:`GNodeArray` class is used
 (see ``examples/cpp/interpolate/interpolate.cpp`` for the source code):
-**Python**
-
-.. code-block:: python
-   :linenos:
-
-   x_i   = [1.0, 4.0, 6.0]
-   y_i   = [8.0, 7.0, 2.0]
-   nodes = gammalib.GNodeArray(x_i)
-   for x in range(20):
-       nodes.set_value(x*0.5)
-       y = y_i[nodes.inx_left()]  * nodes.wgt_left() + y_i[nodes.inx_right()] * nodes.wgt_right()
-       print('x=%f : y=%f' % (x, y))
-
 **C++**
 .. code-block:: cpp
@@ -34,6 +21,20 @@ code illustrates how the :doxy:`GNodeArray` class is used
        std::cout << "x=" << x << " : y=" << y << std::endl;
    }
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   x_i   = [1.0, 4.0, 6.0]
+   y_i   = [8.0, 7.0, 2.0]
+   nodes = gammalib.GNodeArray(x_i)
+   for x in range(20):
+       nodes.set_value(x*0.5)
+       y = y_i[nodes.inx_left()]  * nodes.wgt_left() + y_i[nodes.inx_right()] * nodes.wgt_right()
+       print('x=%f : y=%f' % (x, y))
+
+
 In line 1, the nodes :math:`x_i` at which the function values :math:`y_i`
 are given are declared, the actual function values :math:`y_i` are
 declared in line 2. In line 3, a node array is constructed from the
@@ -14,18 +14,6 @@ media is implemented by the :doxy:`GUrlString` class.
 An example of a class making using of :doxy:`GUrl` is the :doxy:`GXml` class. Look
 at the following code:
-**Python**
-
-.. code-block:: python
-   :linenos:
-
-   xml = gammalib.GXml()
-   xml.append(gammalib.GXmlElement('dummy'))
-   file  = gammalib.GUrlFile('my_file.xml', 'w')
-   chain = gammalib.GUrlString()
-   xml.write(file)
-   xml.write(chain)
-
 **C++**
 .. code-block:: cpp
@@ -38,6 +26,18 @@ at the following code:
    xml.write(file);
    xml.write(chain);
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   xml = gammalib.GXml()
+   xml.append(gammalib.GXmlElement('dummy'))
+   file  = gammalib.GUrlFile('my_file.xml', 'w')
+   chain = gammalib.GUrlString()
+   xml.write(file)
+   xml.write(chain)
+
 Line 1 declares a XML object and in line 2 we append a dummy element
 to it. In line 3 we now create a file named ``my_file.xml`` for which
 we allow write access. In line 4 we allocate a string media. We then
@@ -4,17 +4,6 @@ Random number generation
 Random number generation is widely used within GammaLib for drawing event 
 distributions from functions.
-**Python**
-
-.. code-block:: python
-   :linenos:
-
-   ran         = gammalib.GRan()          # Construct random number generate instance
-   uniform     = ran.uniform()            # Uniform random number
-   exponential = ran.exp(3.7)             # Exponential random number
-   poisson     = ran.poisson(2.4)         # Poisson random number
-   chi2        = ran.chisq2()             # Chi2 random number
-
 **C++**
 .. code-block:: cpp
@@ -26,17 +15,20 @@ distributions from functions.
    double poisson     = ran.poisson(2.4); // Poisson random number
    double chi2        = ran.chisq2();     // Chi2 random number
-In line 1 a random number generator is allocated. If control over the
-seed value of the random number generator is needed (for example to draw
-different samples), you may specify the seed value upon construction:
-
 **Python**
 .. code-block:: python
    :linenos:
-   seed = 123456
-   ran  = gammalib.GRan(seed)
+   ran         = gammalib.GRan()          # Construct random number generate instance
+   uniform     = ran.uniform()            # Uniform random number
+   exponential = ran.exp(3.7)             # Exponential random number
+   poisson     = ran.poisson(2.4)         # Poisson random number
+   chi2        = ran.chisq2()             # Chi2 random number
+
+In line 1 a random number generator is allocated. If control over the
+seed value of the random number generator is needed (for example to draw
+different samples), you may specify the seed value upon construction:
 **C++**
@@ -46,6 +38,14 @@ different samples), you may specify the seed value upon construction:
    unsigned long long int seed = 123456;
    GRan ran(seed);
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   seed = 123456
+   ran  = gammalib.GRan(seed)
+
 The :doxy:`GRan::uniform` method returns a random number between 0 and 1. The
 :doxy:`GRan::exp` method returns a random number of the exponential law