Andreas Specovius / gammalib

Commit c64f50fd67c1307884ad65315b5c6bfae024d548

Authored by Jürgen Knödlseder
1 parent 5ff2e358

Add developer documentation for code generation (#2190)

Inline Side-by-side
Showing 6 changed files with 216 additions and 48 deletions
dev/codegen.py
  View file @c64f50f
... ... @@ -487,7 +487,7 @@ def module_menu():
487 487 author = response('Please enter your name (e.g. "Joe Public")')
488 488  
489 489 # Ask to confirm module summary
490   - print('All right. Have now:')
  490 + print('\nAll right. Have now:')
491 491 print('Module name .....: "%s"' % name)
492 492 print('Instrument name .: "%s"' % instrument)
493 493 print('Your name .......: "%s"' % author)
... ... @@ -513,11 +513,11 @@ def module_menu():
513 513  
514 514 # If all baseclasses are already there then exist now
515 515 if len(baseclasses) == 0:
516   - print('All right. The module exists already and all base classes '
  516 + print('\nAll right. The module exists already and all base classes '
517 517 'are already implemented. Return now to main menu.')
518 518 return
519 519 else:
520   - print('All right. Now lets add some classes:')
  520 + print('\nAll right. Now lets add some classes:')
521 521  
522 522 # Loop over all missing baseclasses
523 523 for baseclass in baseclasses:
... ... @@ -532,7 +532,7 @@ def module_menu():
532 532 baseclasses = ['GObservation', 'GResponse']
533 533  
534 534 # Ask further questions
535   - print('All right. You want a new "%s" instrument module.' % name)
  535 + print('\nAll right. You want a new "%s" instrument module.' % name)
536 536 while True:
537 537 add_list = confirm('Do you want event list support?')
538 538 add_bin = confirm('Do you want binned event data support?')
... ...
doc/source/develop/contributing.rst 0 → 100644
  View file @c64f50f
  1 +.. _dev_contributing:
  2 +
  3 +Contributing to GammaLib
  4 +========================
  5 +
  6 +GammaLib is an open source projet and you are highly welcome to contribute
  7 +to the development.
  8 +Contributions can come in any areas: writing C++ code, contributing Python
  9 +scripts, writing documentation, testing code, etc.
  10 +
  11 +We manage the GammaLib source code using `GitLab <https://cta-gitlab.irap.omp.eu>`_.
  12 +We also have a `Redmine <https://cta-redmine.irap.omp.eu/projects/gammalib/>`_
  13 +development platform to track issues.
  14 +We use a continuous integration system based on
  15 +`Jenkins <https://cta-jenkins.irap.omp.eu>`_
  16 +and we monitor our code quality with
  17 +`SonarQube <https://cta-sonar.irap.omp.eu/overview?id=612>`_.
  18 +
  19 +You may also want to get in the GammaLib information flow by subscribing to
  20 +the ctools@irap.omp.eu mailing list.
  21 +To subscribe simply send an e-mail to ctools-subscribe@irap.omp.eu.
  22 +
  23 +We are organising regular `Coding sprints <https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>`_
  24 +to allow newcomers to get familiar with the code base and the coding practices.
  25 +You are highly invited to join one of the next coding sprints.
  26 +
  27 +You can also follow `@gammalib <https://twitter.com/gammalib>`_ on
  28 +twitter to get informed about new releases of GammaLib.
  29 +
  30 +Below some useful links:
  31 +
  32 +* `GitLab <https://cta-gitlab.irap.omp.eu/gammalib/gammalib>`_
  33 +* `GitHub <https://github.com/gammalib/gammalib>`_
  34 +* `Redmine <https://cta-redmine.irap.omp.eu/projects/gammalib>`_
  35 +* `Open HUB <https://www.openhub.net/p/gammalib>`_
  36 +* `Source code documentation (Doxygen) <../doxygen/index.html>`_
  37 +
  38 +.. image:: https://cta-jenkins.irap.omp.eu/buildStatus/icon?job=gammalib-integrate-os
  39 + :target: https://cta-jenkins.irap.omp.eu/job/gammalib-integrate-os
  40 + :alt: Build Status
  41 +
  42 +.. image:: https://cta-sonar.irap.omp.eu/api/badges/gate?key=gammalib
  43 + :target: https://cta-sonar.irap.omp.eu/dashboard/index/gammalib
  44 + :alt: Quality Gate
... ...
doc/source/develop/howto/index.rst 0 → 100644
  View file @c64f50f
  1 +.. _dev_howto:
  2 +
  3 +Developer's How To
  4 +==================
  5 +
  6 +.. toctree::
  7 + :maxdepth: 1
  8 +
  9 + module/index
  10 +
  11 +
... ...
doc/source/develop/howto/module/codegen.rst 0 → 100644
  View file @c64f50f
  1 +.. _dev_howto_module_codegen:
  2 +
  3 +Add module using the code generator
  4 +===================================
  5 +
  6 + .. admonition:: What you will learn
  7 +
  8 + You will learn how you **add template code for an instrument module
  9 + to GammaLib** using the code generator.
  10 +
  11 +You should use the code generator that is included in GammaLib to add
  12 +a template for a new instrument module to the code base. Let's assume
  13 +that you want to create a module for the
  14 +`DAMPE <http://dpnc.unige.ch/dampe/>`_
  15 +satellite. Before starting, make sure that you get rid of any existing
  16 +compiled code:
  17 +
  18 +.. code-block:: bash
  19 +
  20 + $ make clean
  21 +
  22 +Now you should create a new branch that will contain the new module:
  23 +
  24 +.. code-block:: bash
  25 +
  26 + $ git checkout -b add-dampe-module
  27 +
  28 +To this new branch you should add now the new module using the code
  29 +generator. The code generator in invoked as follows from the root
  30 +of the GammaLib directory:
  31 +
  32 +.. code-block:: bash
  33 +
  34 + $ dev/codegen.py
  35 + GammaLib code generator
  36 + =======================
  37 +
  38 + [1] Add instrument module
  39 + [q] Quit
  40 + Enter your choice:
  41 +
  42 +..
  43 +
  44 + .. note::
  45 +
  46 + Note that you need gammalib installed and configured to use the code
  47 + generator. You can only use the code generator from the root of the
  48 + GammaLib code directory.
  49 +
  50 +Now select ``1`` to add a new instrument module. This will ask you a few
  51 +questions:
  52 +
  53 +.. code-block:: bash
  54 +
  55 + Add instrument module
  56 + ---------------------
  57 + Please enter a 3 digit-name for the module: dam
  58 + Please enter the instrument name (e.g. "Fermi/LAT"): DAMPE
  59 + Please enter your name (e.g. "Joe Public"): Joe Public
  60 +
  61 + All right. Have now:
  62 + Module name .....: "dam"
  63 + Instrument name .: "DAMPE"
  64 + Your name .......: "Joe Public"
  65 + Is this correct? (y/n):
  66 +
  67 +Once you are satisfied with the answers, press ``y``. Now you have to answer
  68 +two more questions about the event format that should be supported. In most
  69 +cases your data will be in form of event list. If this is your case, answer
  70 +``y`` to the first question. In many cases you want to be able to bin the
  71 +data into a counts cube. If this is your case, answer also ``y`` to the second
  72 +question:
  73 +
  74 +.. code-block:: bash
  75 +
  76 + All right. You want a new "dam" instrument module.
  77 + Do you want event list support? (y/n): y
  78 + Do you want binned event data support? (y/n): y
  79 +..
  80 +
  81 + .. note::
  82 +
  83 + The code generator also allows to add <missing `dev_howto_module_missing`>
  84 + classes later, so if you are not yet sure you may also answer ``n``
  85 + for now.
  86 +
  87 +Now you are done. Enter ``q`` to exit the code generator.
  88 +
  89 +You put the new code under
  90 +`Git <https://git-scm.com/>`_
  91 +control by typing
  92 +
  93 +.. code-block:: bash
  94 +
  95 + $ git add .
  96 + $ git commit -m "Add code templates for DAMPE instrument module"
  97 + [add-dampe-module c573eff] Add code templates for DAMPE instrument module
  98 + 39 files changed, 5288 insertions(+), 13 deletions(-)
  99 + create mode 100644 inst/dam/Makefile.am
  100 + create mode 100644 inst/dam/README.md
  101 + create mode 100644 inst/dam/include/GDAMEventAtom.hpp
  102 + create mode 100644 inst/dam/include/GDAMEventBin.hpp
  103 + create mode 100644 inst/dam/include/GDAMEventCube.hpp
  104 + create mode 100644 inst/dam/include/GDAMEventList.hpp
  105 + create mode 100644 inst/dam/include/GDAMInstDir.hpp
  106 + create mode 100644 inst/dam/include/GDAMLib.hpp
  107 + create mode 100644 inst/dam/include/GDAMObservation.hpp
  108 + create mode 100644 inst/dam/include/GDAMResponse.hpp
  109 + create mode 100644 inst/dam/include/GDAMRoi.hpp
  110 + create mode 100644 inst/dam/pyext/GDAMEventAtom.i
  111 + create mode 100644 inst/dam/pyext/GDAMEventBin.i
  112 + create mode 100644 inst/dam/pyext/GDAMEventCube.i
  113 + create mode 100644 inst/dam/pyext/GDAMEventList.i
  114 + create mode 100644 inst/dam/pyext/GDAMInstDir.i
  115 + create mode 100644 inst/dam/pyext/GDAMObservation.i
  116 + create mode 100644 inst/dam/pyext/GDAMResponse.i
  117 + create mode 100644 inst/dam/pyext/GDAMRoi.i
  118 + create mode 100644 inst/dam/pyext/dam.i
  119 + create mode 100644 inst/dam/src/GDAMEventAtom.cpp
  120 + create mode 100644 inst/dam/src/GDAMEventBin.cpp
  121 + create mode 100644 inst/dam/src/GDAMEventCube.cpp
  122 + create mode 100644 inst/dam/src/GDAMEventList.cpp
  123 + create mode 100644 inst/dam/src/GDAMInstDir.cpp
  124 + create mode 100644 inst/dam/src/GDAMObservation.cpp
  125 + create mode 100644 inst/dam/src/GDAMResponse.cpp
  126 + create mode 100644 inst/dam/src/GDAMRoi.cpp
  127 + create mode 100644 inst/dam/test/Makefile.am
  128 + create mode 100644 inst/dam/test/test_DAM.cpp
  129 + create mode 100644 inst/dam/test/test_DAM.hpp
  130 + create mode 100644 inst/dam/test/test_DAM.py
  131 + $ git push origin add-dampe-module
  132 +
  133 +Finally, configure and compile your code, including the new module, by
  134 +typing
  135 +
  136 +.. code-block:: bash
  137 +
  138 + $ autoconf
  139 + $ automake
  140 + $ ./configure
  141 + $ make
  142 + $ make check
... ...
doc/source/develop/howto/module/index.rst 0 → 100644
  View file @c64f50f
  1 +.. _dev_howto_module:
  2 +
  3 +How to add an instrument module?
  4 +================================
  5 +
  6 + .. admonition:: What you will learn
  7 +
  8 + You will learn how you **add an instrument module to GammaLib**.
  9 +
  10 +.. toctree::
  11 + :maxdepth: 1
  12 +
  13 + codegen
... ...
doc/source/develop/index.rst
  View file @c64f50f
... ... @@ -3,54 +3,12 @@
3 3 Developer documentation
4 4 =======================
5 5  
6   -GammaLib is an open source projet and you are highly welcome to contribute
7   -to the development.
8   -Contributions can come in any areas: writing C++ code, contributing Python
9   -scripts, writing documentation, testing code, etc.
10   -
11   -We manage the GammaLib source code using `GitLab <https://cta-gitlab.irap.omp.eu>`_.
12   -We also have a `Redmine <https://cta-redmine.irap.omp.eu/projects/gammalib/>`_
13   -development platform to track issues.
14   -We use a continuous integration system based on
15   -`Jenkins <https://cta-jenkins.irap.omp.eu>`_
16   -and we monitor our code quality with
17   -`SonarQube <https://cta-sonar.irap.omp.eu/overview?id=612>`_.
18   -
19   -You may also want to get in the GammaLib information flow by subscribing to
20   -the ctools@irap.omp.eu mailing list.
21   -To subscribe simply send an e-mail to ctools-subscribe@irap.omp.eu.
22   -
23   -We are organising regular `Coding sprints <https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>`_
24   -to allow newcomers to get familiar with the code base and the coding practices.
25   -You are highly invited to join one of the next coding sprints.
26   -
27   -You can also follow `@gammalib <https://twitter.com/gammalib>`_ on
28   -twitter to get informed about new releases of GammaLib.
29   -
30   -Below a few links to learn how to contribute to GammaLib:
31   -
32 6 .. toctree::
33 7 :maxdepth: 1
34 8  
  9 + contributing
  10 + howto/index
35 11 git/index
36 12 coding/index
37 13 profiling/index
38 14 releasing/index
39   -
40   -Links:
41   -
42   -* `GitLab <https://cta-gitlab.irap.omp.eu/gammalib/gammalib>`_
43   -* `GitHub <https://github.com/gammalib/gammalib>`_
44   -* `Redmine <https://cta-redmine.irap.omp.eu/projects/gammalib>`_
45   -* `Open HUB <https://www.openhub.net/p/gammalib>`_
46   -* `Source code documentation (Doxygen) <../doxygen/index.html>`_
47   -
48   -And here some status shields:
49   -
50   -.. image:: https://cta-jenkins.irap.omp.eu/buildStatus/icon?job=gammalib-integrate-os
51   - :target: https://cta-jenkins.irap.omp.eu/job/gammalib-integrate-os
52   - :alt: Build Status
53   -
54   -.. image:: https://cta-sonar.irap.omp.eu/api/badges/gate?key=gammalib
55   - :target: https://cta-sonar.irap.omp.eu/dashboard/index/gammalib
56   - :alt: Quality Gate
... ...