How to use git?
===============

Anyone who has access to the Git platform is welcome to edit and improve the contents of the repositories. However, in order to ensure that things don't get ugly, `"Developer" access <https://docs.gitlab.com/ee/user/permissions.html>`_ was granted to all members, meaning that in order to push the commits to the main master branch (i.e. the one used for production), you will need to perform a :ref:`Merge Request <merge_request>`.

.. _merge_request:

Do Merge Requests
-----------------

If you want to edit the content of a repository for which you don't have "Master" access, you can still ask for your edits to be reflected in the master branch by doing what is called a `Merge Request <https://docs.gitlab.com/ee/user/project/merge_requests/>`_. This can be done as follows:

1. As usual, clone the repository you want to edit, e.g.::

     git clone https://gitlab.com/hpo-uq/hyppo.git

2. From the repository you just cloned, create and switch to a local branch in which you can do the edit::

     git checkout -b mybranch

3. Once you have done all the edits you wanted, you can push the branch on the git server::

     git push origin mybranch
   
4. Once your branch has been pushed to the remote server, you will see a ``Create merge request`` option on the online webpage of the repository you cloned. Click on edit and submit the request.

Future edits
------------
   
For future edits, you can simply pull new updates from the master branch onto your local branch. Use the ``--rebase`` option to ensure that your un-committed changes are not overwritten::

     git pull --rebase origin master

Future edits on your local branch can then be pushed to the remote server::

     git add .
     git commit -m "new commit message"
     git push origin mybranch

If you wish to delete your local branch, this can be done as follows::

     # Switch to master branch
     git checkout master
     # Delete local branch
     git branch -d mybranch

Loading submodule
-----------------

All the product files from this documentation can be found within `this separate Gitlab repository <https://gitlab.com/hpo-uq/docs>`_ which needs to be loaded as submodule within the `HYPPO repository <https://gitlab.com/hpo-uq/hyppo>`_ in order to compile properly, this can be done by typing the following command within the software's repository::

    git submodule init
    git submodule update

.. _sphinx:

Sphinx libraries
----------------

This documentation is built using the `Sphinx documentation-generator library <https://www.sphinx-doc.org/en/master/>`_. The pages are written in reStructuredText file format (``.rst``) and get compiled into HTML through the supplied Makefile. In order to compile properly, the following Python packages need to be installed in the system:

.. literalinclude:: ../requirements.txt

The above list is contained within a :download:`requirements.txt<../requirements.txt>` file, all the dependencies can then be installed using the following ``pip`` command::

    pip install -r requirements.txt