Reorganise ctools documentation

Jürgen Knödlseder
1 parent cc5e351c
Showing 94 changed files with 329 additions and 57 deletions
doc/source/_templates/index.html
doc/source/_themes/sphinx13/layout.html
doc/source/contents.rst
doc/source/develop.rst
doc/source/coding/cpp.rst → doc/source/develop/coding/cpp.rst
doc/source/coding/general.rst → doc/source/develop/coding/general.rst
doc/source/coding/index.rst → doc/source/develop/coding/index.rst
doc/source/coding/introduction.rst → doc/source/develop/coding/introduction.rst
doc/source/coding/python.rst → doc/source/develop/coding/python.rst
doc/source/develop/git/git-workflow.png
doc/source/develop/git/gitlab-fork-step1.jpg
doc/source/develop/git/gitlab-fork-step2.jpg
doc/source/develop/git/gitlab-fork-step3.jpg
doc/source/develop/git/gitlab-push.jpg
doc/source/develop/git/index.rst
doc/source/develop/git/pull-request.jpg
doc/source/develop/index.rst
doc/source/faq.rst → doc/source/users/faq.rst
doc/source/help.rst → doc/source/users/help.rst
doc/source/users/index.rst
@@ -37,28 +37,29 @@ and next steps, and advance with the coding of the software. {%endtrans%}&lt;/p&gt;
 <h2 style="margin-bottom: 0">{%trans%}Getting started{%endtrans%}</h2>
 <ul>
-<li><a class="smalllink" href="{{ pathto("user_manual/getting") }}">{%trans%}Installation{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("user_manual/getting_started/quickstart") }}">{%trans%}Quickstart{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("user_manual/getting_started/beyond") }}">{%trans%}Beyond the first steps{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("user_manual/getting_started/models") }}">{%trans%}Modelling CTA data{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("user_manual/getting_started/response") }}">{%trans%}CTA response functions{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("user_manual/getting_started/python") }}">{%trans%}Using ctools from Python{%endtrans%}</a></li> 
+<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("user_manual/index") }}">{%trans%}User Manual{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("reference_manual/index") }}">{%trans%}Reference Manual{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("faq") }}">{%trans%}Frequently asked questions{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("issues") }}">{%trans%}Known issues{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("coding/index") }}">{%trans%}Coding conventions{%endtrans%}</a></li> 
-<li><a class="smalllink" href="doxygen/index.html">{%trans%}Source code documentation (Doxygen){%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="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-redmine.irap.omp.eu/projects/ctools">Developer's pages</a></li>
-	<li><a href="https://www.openhub.net/p/ctools_">ctools on Open HUB</a>{% endblock %}</li>
+	<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>
@@ -70,9 +70,9 @@
   <ul>
     <li><a href="{{ pathto('about') }}">About</a></li>
     <li><a href="{{ pathto('download') }}">Download</a></li>
-    <li><a href="{{ pathto('contents') }}">Documentation</a></li>
-    <li><a href="{{ pathto('develop') }}">Develop</a></li>
-    <li><a href="{{ pathto('help') }}">Help</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>
   </ul>
   <div>
     <a href="{{ pathto('index') }}">
@@ -2,14 +2,9 @@ Documentation
 =============
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    about
    download
-   user_manual/index
-   reference_manual/index
-   faq
-   issues
-   develop
-   coding/index
-   help
+   users/index
+   develop/index
-.. _develop:
-
-Develop
-=======
-
-ctools 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.
-
-The ctools software development is managed by a
-`Redmine <https://cta-redmine.irap.omp.eu/projects/ctools/>`_ platform.
-Please check out the 
-`Wiki <https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Contributing_to_ctools>`_
-on that platform to learn how you can contribute to the ctools software
-development.
-
-You may also want to get in the ctools 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 `@ctools_software <https://twitter.com/ctools_software>`_ on
-twitter to get informed about new ctools releases.
 \ No newline at end of file
+.. _git:
+
+Using Git and GitLab
+====================
+
+The ctools source code is version controlled using
+`Git <https://git-scm.com/>`_ that is managed through a
+`GitLab <https://cta-gitlab.irap.omp.eu/ctools/ctools>`_ web interface.
+
+Every developer will create a user in
+`GitLab <https://cta-gitlab.irap.omp.eu/ctools/ctools>`_
+and have an own copy (a so called fork) of the ctools code in his/her
+user space.
+There is hence no need or possibility to push to the main ctools repository.
+Once you forked from the ctools repository, you can create
+feature branches and add some new code (or correct a bug), and issue a pull
+request so that your change gets included in the trunk.
+Note that we do not use
+`GitLab's <https://cta-gitlab.irap.omp.eu/ctools/ctools>`_
+pull request feature  for the moment, as all issues are tracked on our
+`Redmine <https://cta-redmine.irap.omp.eu/projects/ctools>`_
+system, but this may change in the future.
+Our `Git <https://git-scm.com/>`_ workflow is identical to the one you
+typically use on `GitHub <https://github.com/ctools/ctools>`_.
+You may in fact also use `GitHub <https://github.com/ctools/ctools>`_
+for your code developments, as the ctools source code is mirrored to
+`GitHub <https://github.com/ctools/ctools>`_ in a read only repository.
+
+
+Before you start
+----------------
+
+Make sure you configured your `Git <https://git-scm.com/>`_ using your user
+name and e-mail address (you only need to do this once on your machine):
+
+.. code-block:: sh
+
+   $ git config --global user.name "John Doe"
+   $ git config --global user.email johndoe@example.com
+
+In addition, you may need to add
+
+.. code-block:: sh
+
+   $ git config --global http.sslverify "false"
+
+so that you have no SSL certificate error when you access the
+repository.
+
+
+Overview
+--------
+
+The figure below illustrates the `Git <https://git-scm.com/>`_ workflow
+that we use for the ctools development.
+Permanent branches are shown as black lines, temporary branches as grey lines.
+The yellow area is the ctools repository, the light blue area is your
+forked user space.
+There are three permanent branches in the ctools repository:
+
+* the ``master`` branch that holds the latest release
+* the ``devel`` branch that is the trunk on which development progresses
+* the ``integration`` branch that is used for code integration
+
+A temporary ``release`` branch is used for hotfixes and generally for code
+testing prior to any release.
+As developer you will work in your user space and work on temporary
+``feature`` branches.
+
+.. image:: git-workflow.png
+   :height: 400px
+   :alt: Git workflow
+   :align: center
+
+
+Forking the project
+-------------------
+
+As the first step you need to create a fork of the project in your user
+space.
+Connect to `GitLab <https://cta-gitlab.irap.omp.eu/ctools/ctools>`_
+using your Redmine user name and password (if you have not yet an
+account on
+`Redmine <https://cta-redmine.irap.omp.eu/projects/ctools>`_ then go
+ahead and create one).
+Select the `ctools <https://cta-gitlab.irap.omp.eu/ctools/ctools>`_
+project and click on ``Fork`` (see below).
+
+.. image:: gitlab-fork-step1.jpg
+   :width: 600px
+   :alt: Forking the ctools repository
+   :align: center
+
+This brings you to a screen that invites you to fork the project into
+your user space.
+Click on your user (see below).
+
+.. image:: gitlab-fork-step2.jpg
+   :width: 600px
+   :alt: Select user
+   :align: center
+
+After a short while a fork will be created that now is under your
+ownership (see below).
+
+.. image:: gitlab-fork-step3.jpg
+   :width: 600px
+   :alt: Forked created successfully
+   :align: center
+
+Now you can clone this fork using
+
+.. code-block:: sh
+
+   $ git clone https://cta-gitlab.irap.omp.eu/[user]/ctools.git
+
+where ``[user]`` is your
+`GitLab <https://cta-gitlab.irap.omp.eu/ctools/ctools>`_
+(or `Redmine <https://cta-redmine.irap.omp.eu/projects/ctools>`_)
+user name.
+To keep in sync with the ctools repository you should add it as
+a remote repository using
+
+.. code-block:: sh
+
+   $ git remote add upstream https://cta-gitlab.irap.omp.eu/ctools/ctools.git
+
+You can then type
+
+.. code-block:: sh
+
+   $ git pull upstream devel
+
+to pull in changes from the ``devel`` branch of ctools in your
+repository.
+
+
+Modifying or adding code
+------------------------
+
+To work on a new feature or to correct a bug you should always create a new
+branch.
+You do this by typing
+
+.. code-block:: sh
+
+   $ git checkout devel
+   $ git pull upstream devel
+   $ git checkout -b 9101-skymap-smooth-method
+
+which makes sure that you are on your ``devel`` branch, then pulls in changes
+from the ctools repository, and finally creates the
+``9101-skymap-smooth-method`` branch.
+New branches should always start with an issue number, followed by
+a meaningful name that indicates what the branch is good for (use hyphens
+to separate words).
+You can find the relevant issue number using the
+`Redmine issue tracker <https://cta-redmine.irap.omp.eu/projects/ctools/issues>`_.
+
+Suppose that your goal is to add a ``smooth()`` method to the ``GSkyMap``
+class.
+You would then add this method to ``GSkyMap`` by editing the
+``GSkyMap.hpp``, ``GSkyMap.cpp`` and ``GSkyMap.i`` files.
+You should also add unit tests for the new method, and you would do
+this by editing the ``test_GSky.hpp`` and ``test_GSky.cpp`` files.
+Once you have verified that the new method works you should commit
+your changes.
+
+First stage all files you want to commit.
+To commit for example only the new class method you should type
+
+.. code-block:: sh
+
+   $ git add src/sky/GSkyMap.hpp
+   $ git add src/sky/GSkyMap.cpp
+   $ git add src/sky/GSkyMap.i
+
+followed by
+
+.. code-block:: sh
+
+   $ git commit -m "Add GSkyMap::smooth() method (#9101)
+   >
+   > The GSkyMap::smooth() allows the smoothing of sky maps using
+   > various kernels."
+
+where the message in quotes should be comprised of a single line subject
+that describes what was changed, and a message body that describes why
+the change was made. Subject line and message body should be separated
+by a blank line (see `How to Write a Git Commit Message
+<http://chris.beams.io/posts/git-commit/>`_).
+
+You should then also stage and commit the remaining files.
+
+To make the changes available to other users, and specifically to allow
+their merging into the ctools repository, you need to push you local
+changes into your
+`GitLab's <https://cta-gitlab.irap.omp.eu/ctools/ctools>`_
+repository.
+You do this by typing
+
+.. code-block:: sh
+
+   $ git push origin 9101-skymap-smooth-method
+
+Note that the ``origin`` argument specifies that you want to push your
+changes into the same repository from which you cloned the code.
+
+You can now verify on
+`GitLab's <https://cta-gitlab.irap.omp.eu/ctools/ctools>`_
+that a new branch exists in your project:
+
+.. image:: gitlab-push.jpg
+   :width: 600px
+   :alt: Pushing a new branch
+   :align: center
+
+
+Creating a pull request
+-----------------------
+
+Once the code is pushed into your repository you can create a request that
+your code should be merged into the ctools repository.
+For this you have to open the relevant issue in the
+`Redmine issue tracker <https://cta-redmine.irap.omp.eu/projects/ctools/issues>`_
+and put the status of the issue to ``Pull request``:
+
+.. image:: pull-request.jpg
+   :width: 600px
+   :alt: Creating a pull request
+   :align: center
+
+You should indiciate in the notes in which repository and on which branch
+your change is.
+You should also describe the changes or addition you made to the code.
+Explain what you have done. Say if there is anything you’d like particular
+attention for - like a complicated change or some code you are not happy
+with.
+If you don’t think your request is ready to be merged, just say so in your
+pull request message.
+This is still a good way of getting some preliminary code review.
+.. _develop:
+
+Developer documentation
+=======================
+
+ctools 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 ctools source code using `GitLab <https://cta-gitlab.irap.omp.eu>`_.
+We also have a `Redmine <https://cta-redmine.irap.omp.eu/projects/ctools/>`_
+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=3055>`_.
+
+You may also want to get in the ctools 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 `@ctools_software <https://twitter.com/ctools_software>`_ on
+twitter to get informed about new ctools releases.
+
+Below a few links to learn how to contribute to ctools:
+
+.. toctree::
+   :maxdepth: 1
+
+   git/index
+   coding/index
+
+And here some status shields:
+
+.. image:: https://cta-jenkins.irap.omp.eu/buildStatus/icon?job=ctools-integrate-os
+   :target: https://cta-jenkins.irap.omp.eu/job/ctools-integrate-os
+   :alt: Build Status
+
+.. image:: https://cta-sonar.irap.omp.eu/api/badges/gate?key=ctools
+   :target: https://cta-sonar.irap.omp.eu/dashboard/index/ctools
+   :alt: Quality Gate
+.. _users:
+
+User Documentation
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   user_manual/getting
+   user_manual/getting_started/index
+   user_manual/index
+   reference_manual/index
+   faq
+   issues
+   help
@@ -33,8 +33,8 @@ ctools
    ctulimit --- Calculates upper limit <ctulimit>
-General cscripts
-----------------
+cscripts
+--------
 .. toctree::
    :maxdepth: 1
@@ -53,8 +53,8 @@ General cscripts
    cstsmapmerge --- Merges slices from ts map computations <cstsmapmerge>
-IACT cscripts
--------------
+Scripts to manage an IACT database
+----------------------------------
 .. toctree::
    :maxdepth: 1