.. _adding_projects:

********************************
Adding a New Project from GitLab
********************************

Adding a new project from GitLab is simple. Before you start, you need to
assure that a few prerequisites are met:

- your project has a sphinx compatible `conf.py` somewhere in its directory
  structure and a sphinx build with this files succeeds. See
  :ref:`non_karabo_projects` for information on how to create such a file.

- you do not have any special theme or style set in your `conf.py`. If you do
  please remove them.

- your project is hosted on our GitLab server. If it is publically available
  you can skip on to :ref:`adding_to_rtd`, if not read on at
  :ref:`private_gitlab_projects`.



.. _private_gitlab_projects:

Adding an Access Token
======================

For private GitLab projects RTD needs some way to access these. As we cannot
provide ssh keys for every project, and project's may have different members
the acccess token offers a solution to this. To generate a personal access
token navigate to your profile settings on GitLab and then on to "Access
Tokens".


.. image:: ./_images/profile_settings.png

In the access token dialog give it a meaninful name, e.g. readthedocs, and
select api as "scope". Clicking on "Create Personal Access Tokens" will create
a token - be sure to save this somewhere, as it will not be retrievable
after you leave the page.

.. image:: ./_images/accesstoken.png

Copy this token for later usage.

.. _adding_to_rtd:

Adding Your Project to RTD
==========================

To add your project to RTD navigate to the RTD website and make sure you are
logged in. You can log-in with your LDAP credentials. Given you are a member
of the right group you will have the rights to create projects.

.. image:: ./_images/RTD_Start.png

On the next page you can add a new project. For use with XFEL's internal
GitLab server select *Import Manually*.

.. image:: ./_images/RTD_Manual_Project.png

You will then be asked to give a project name (please choose something
appropriate for your project), as well as the Gitlab location.

.. image:: ./_images/Public_Project.png

The location can be copied from GitLab on the project main page. Make sure
you select the *https* address, not *ssh*:

.. image:: ./_images/GIT_Link.png


In case your repository is private you will now need to insert the access
token into this address. It should have the form:
`https://YOUR_LOGIN:YOUR_TOKEN@git.xfel.eu/...`

Where "YOUR_LOGIN" is your gitlab user name. Upon confirmation this page may
not directly redirect. This depends on how much there is to clone. You can
however go back to the main page and then
click on your projects:

.. image:: ./_images/RTD_Project_List.png

In the *Builds* menu you can check the status of the documentation build for
your project.

.. image:: ./_images/RTD_Build_Status.png

Enabling GitLab Webhooks
========================

Note that RTD complains that you do not yet have a webhook set-up for this
project. This means that new documentation builds will not be trigger upon
commits to your project's git. We can remedy this in GitLab. Click on your
project menu and select the *Webhooks* entry:

.. image:: ./_images/GIT_Webhook_Menu.png

In the following dialog add the URL to XFEL's RTD server in the appropriate
field: `https://in.xfel.eu/readthedocs/gitlab`. Select for which events on
GitLab a new documentation build should be triggered. For Projects it is
recommended
to select *Push events*, for devices it is recommended to select *Tag events*.

.. image:: ./_images/GIT_Webhooks.png

After clicking *Add Webhook* the new webhook will appear in the bottom list.
You can test it from there (will trigger a documentation build of your project).