Add developer documentation for code generation (#2190)

Jürgen Knödlseder
1 parent 5ff2e358
Showing 6 changed files with 216 additions and 48 deletions
dev/codegen.py
doc/source/develop/contributing.rst
doc/source/develop/howto/index.rst
doc/source/develop/howto/module/codegen.rst
doc/source/develop/howto/module/index.rst
doc/source/develop/index.rst
@@ -487,7 +487,7 @@ def module_menu():
         author     = response('Please enter your name (e.g. "Joe Public")')
         # Ask to confirm module summary
-        print('All right. Have now:')
+        print('\nAll right. Have now:')
         print('Module name .....: "%s"' % name)
         print('Instrument name .: "%s"' % instrument)
         print('Your name .......: "%s"' % author)
@@ -513,11 +513,11 @@ def module_menu():
         # If all baseclasses are already there then exist now
         if len(baseclasses) == 0:
-            print('All right. The module exists already and all base classes '
+            print('\nAll right. The module exists already and all base classes '
                   'are already implemented. Return now to main menu.')
             return
         else:
-            print('All right. Now lets add some classes:')
+            print('\nAll right. Now lets add some classes:')
         # Loop over all missing baseclasses
         for baseclass in baseclasses:
@@ -532,7 +532,7 @@ def module_menu():
         baseclasses = ['GObservation', 'GResponse']
         # Ask further questions
-        print('All right. You want a new "%s" instrument module.' % name)
+        print('\nAll right. You want a new "%s" instrument module.' % name)
         while True:
             add_list = confirm('Do you want event list support?')
             add_bin  = confirm('Do you want binned event data support?')
+.. _dev_contributing:
+
+Contributing to GammaLib
+========================
+
+GammaLib is an open source projet and you are highly welcome to contribute
+to the development.
+Contributions can come in any areas: writing C++ code, contributing Python 
+scripts, writing documentation, testing code, etc.
+
+We manage the GammaLib source code using `GitLab <https://cta-gitlab.irap.omp.eu>`_.
+We also have a `Redmine <https://cta-redmine.irap.omp.eu/projects/gammalib/>`_
+development platform to track issues.
+We use a continuous integration system based on
+`Jenkins <https://cta-jenkins.irap.omp.eu>`_
+and we monitor our code quality with
+`SonarQube <https://cta-sonar.irap.omp.eu/overview?id=612>`_.
+
+You may also want to get in the GammaLib information flow by subscribing to 
+the ctools@irap.omp.eu mailing list.
+To subscribe simply send an e-mail to ctools-subscribe@irap.omp.eu.
+
+We are organising regular `Coding sprints <https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>`_
+to allow newcomers to get familiar with the code base and the coding practices.
+You are highly invited to join one of the next coding sprints.
+
+You can also follow `@gammalib <https://twitter.com/gammalib>`_ on
+twitter to get informed about new releases of GammaLib.
+
+Below some useful links:
+
+* `GitLab <https://cta-gitlab.irap.omp.eu/gammalib/gammalib>`_
+* `GitHub <https://github.com/gammalib/gammalib>`_
+* `Redmine <https://cta-redmine.irap.omp.eu/projects/gammalib>`_
+* `Open HUB <https://www.openhub.net/p/gammalib>`_
+* `Source code documentation (Doxygen) <../doxygen/index.html>`_
+
+.. image:: https://cta-jenkins.irap.omp.eu/buildStatus/icon?job=gammalib-integrate-os
+   :target: https://cta-jenkins.irap.omp.eu/job/gammalib-integrate-os
+   :alt: Build Status
+
+.. image:: https://cta-sonar.irap.omp.eu/api/badges/gate?key=gammalib
+   :target: https://cta-sonar.irap.omp.eu/dashboard/index/gammalib
+   :alt: Quality Gate
+.. _dev_howto:
+
+Developer's How To
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   module/index
+
+
+.. _dev_howto_module_codegen:
+
+Add module using the code generator
+===================================
+
+  .. admonition:: What you will learn
+
+     You will learn how you **add template code for an instrument module
+     to GammaLib** using the code generator.
+
+You should use the code generator that is included in GammaLib to add
+a template for a new instrument module to the code base. Let's assume
+that you want to create a module for the
+`DAMPE <http://dpnc.unige.ch/dampe/>`_
+satellite. Before starting, make sure that you get rid of any existing
+compiled code:
+
+.. code-block:: bash
+
+   $ make clean
+
+Now you should create a new branch that will contain the new module:
+
+.. code-block:: bash
+
+   $ git checkout -b add-dampe-module
+
+To this new branch you should add now the new module using the code
+generator. The code generator in invoked as follows from the root
+of the GammaLib directory:
+
+.. code-block:: bash
+
+   $ dev/codegen.py
+   GammaLib code generator
+   =======================
+
+   [1] Add instrument module
+   [q] Quit
+   Enter your choice:
+
+..
+
+  .. note::
+
+     Note that you need gammalib installed and configured to use the code
+     generator. You can only use the code generator from the root of the
+     GammaLib code directory.
+
+Now select ``1`` to add a new instrument module. This will ask you a few
+questions:
+
+.. code-block:: bash
+
+   Add instrument module
+   ---------------------
+   Please enter a 3 digit-name for the module: dam
+   Please enter the instrument name (e.g. "Fermi/LAT"): DAMPE
+   Please enter your name (e.g. "Joe Public"): Joe Public
+
+   All right. Have now:
+   Module name .....: "dam"
+   Instrument name .: "DAMPE"
+   Your name .......: "Joe Public"
+   Is this correct? (y/n):
+
+Once you are satisfied with the answers, press ``y``. Now you have to answer
+two more questions about the event format that should be supported. In most
+cases your data will be in form of event list. If this is your case, answer
+``y`` to the first question. In many cases you want to be able to bin the
+data into a counts cube. If this is your case, answer also ``y`` to the second
+question:
+
+.. code-block:: bash
+
+  All right. You want a new "dam" instrument module.
+  Do you want event list support? (y/n): y
+  Do you want binned event data support? (y/n): y
+..
+
+  .. note::
+
+     The code generator also allows to add <missing `dev_howto_module_missing`>
+     classes later, so if you are not yet sure you may also answer ``n``
+     for now.
+
+Now you are done. Enter ``q`` to exit the code generator.
+
+You put the new code under
+`Git <https://git-scm.com/>`_
+control by typing
+
+.. code-block:: bash
+
+   $ git add .
+   $ git commit -m "Add code templates for DAMPE instrument module"
+   [add-dampe-module c573eff] Add code templates for DAMPE instrument module
+    39 files changed, 5288 insertions(+), 13 deletions(-)
+    create mode 100644 inst/dam/Makefile.am
+    create mode 100644 inst/dam/README.md
+    create mode 100644 inst/dam/include/GDAMEventAtom.hpp
+    create mode 100644 inst/dam/include/GDAMEventBin.hpp
+    create mode 100644 inst/dam/include/GDAMEventCube.hpp
+    create mode 100644 inst/dam/include/GDAMEventList.hpp
+    create mode 100644 inst/dam/include/GDAMInstDir.hpp
+    create mode 100644 inst/dam/include/GDAMLib.hpp
+    create mode 100644 inst/dam/include/GDAMObservation.hpp
+    create mode 100644 inst/dam/include/GDAMResponse.hpp
+    create mode 100644 inst/dam/include/GDAMRoi.hpp
+    create mode 100644 inst/dam/pyext/GDAMEventAtom.i
+    create mode 100644 inst/dam/pyext/GDAMEventBin.i
+    create mode 100644 inst/dam/pyext/GDAMEventCube.i
+    create mode 100644 inst/dam/pyext/GDAMEventList.i
+    create mode 100644 inst/dam/pyext/GDAMInstDir.i
+    create mode 100644 inst/dam/pyext/GDAMObservation.i
+    create mode 100644 inst/dam/pyext/GDAMResponse.i
+    create mode 100644 inst/dam/pyext/GDAMRoi.i
+    create mode 100644 inst/dam/pyext/dam.i
+    create mode 100644 inst/dam/src/GDAMEventAtom.cpp
+    create mode 100644 inst/dam/src/GDAMEventBin.cpp
+    create mode 100644 inst/dam/src/GDAMEventCube.cpp
+    create mode 100644 inst/dam/src/GDAMEventList.cpp
+    create mode 100644 inst/dam/src/GDAMInstDir.cpp
+    create mode 100644 inst/dam/src/GDAMObservation.cpp
+    create mode 100644 inst/dam/src/GDAMResponse.cpp
+    create mode 100644 inst/dam/src/GDAMRoi.cpp
+    create mode 100644 inst/dam/test/Makefile.am
+    create mode 100644 inst/dam/test/test_DAM.cpp
+    create mode 100644 inst/dam/test/test_DAM.hpp
+    create mode 100644 inst/dam/test/test_DAM.py
+  $ git push origin add-dampe-module
+
+Finally, configure and compile your code, including the new module, by
+typing
+
+.. code-block:: bash
+
+   $ autoconf
+   $ automake
+   $ ./configure
+   $ make
+   $ make check
+.. _dev_howto_module:
+
+How to add an instrument module?
+================================
+
+  .. admonition:: What you will learn
+
+     You will learn how you **add an instrument module to GammaLib**.
+
+.. toctree::
+   :maxdepth: 1
+
+   codegen
@@ -3,54 +3,12 @@
 Developer documentation
 =======================
-GammaLib is an open source projet and you are highly welcome to contribute
-to the development.
-Contributions can come in any areas: writing C++ code, contributing Python 
-scripts, writing documentation, testing code, etc.
-
-We manage the GammaLib source code using `GitLab <https://cta-gitlab.irap.omp.eu>`_.
-We also have a `Redmine <https://cta-redmine.irap.omp.eu/projects/gammalib/>`_
-development platform to track issues.
-We use a continuous integration system based on
-`Jenkins <https://cta-jenkins.irap.omp.eu>`_
-and we monitor our code quality with
-`SonarQube <https://cta-sonar.irap.omp.eu/overview?id=612>`_.
-
-You may also want to get in the GammaLib information flow by subscribing to 
-the ctools@irap.omp.eu mailing list.
-To subscribe simply send an e-mail to ctools-subscribe@irap.omp.eu.
-
-We are organising regular `Coding sprints <https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>`_
-to allow newcomers to get familiar with the code base and the coding practices.
-You are highly invited to join one of the next coding sprints.
-
-You can also follow `@gammalib <https://twitter.com/gammalib>`_ on
-twitter to get informed about new releases of GammaLib.
-
-Below a few links to learn how to contribute to GammaLib:
-
 .. toctree::
    :maxdepth: 1
+   contributing
+   howto/index
    git/index
    coding/index
    profiling/index
    releasing/index
-
-Links:
-
-* `GitLab <https://cta-gitlab.irap.omp.eu/gammalib/gammalib>`_
-* `GitHub <https://github.com/gammalib/gammalib>`_
-* `Redmine <https://cta-redmine.irap.omp.eu/projects/gammalib>`_
-* `Open HUB <https://www.openhub.net/p/gammalib>`_
-* `Source code documentation (Doxygen) <../doxygen/index.html>`_
-
-And here some status shields:
-
-.. image:: https://cta-jenkins.irap.omp.eu/buildStatus/icon?job=gammalib-integrate-os
-   :target: https://cta-jenkins.irap.omp.eu/job/gammalib-integrate-os
-   :alt: Build Status
-
-.. image:: https://cta-sonar.irap.omp.eu/api/badges/gate?key=gammalib
-   :target: https://cta-sonar.irap.omp.eu/dashboard/index/gammalib
-   :alt: Quality Gate