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 Non-Karabo-Related Documentation 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 Adding Your Project to RTD, if not read on at Adding an Access Token.

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”.

_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.

_images/accesstoken.png

Copy this token for later usage.

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.

_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.

_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.

_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:

_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:

_images/RTD_Project_List.png

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

_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:

_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.

_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).