.. include:: images.rst

########################################
Building Documentation for GitLab Pages
########################################

|TBU|

.. attention::
   Currently the building of cWB documentation is done via a CI script. 
   The old method consisting in creating an ad-hoc 
   orphaned branch, gl-pages, is mostly outdated.

| |cWB|

===============================
Creating a GitLab project page
===============================

GitLab pages are built from a branch of the repository called ``gl-pages``.
If you have not already created a GitLab project pages for cWB in your
repository, make a ``gl-pages`` branch in your repository as follows:

.. code-block:: bash

    git checkout --orphan gl-pages
    git rm -rf .
    git clean -dxf
    touch .nojekyll
    mkdir latest
    git add .nojekyll latest
    git commit -a -m "set up gl-pages branch"
    git push shared gl-pages
    git branch --set-upstream-to=shared/gl-pages

These commands create the branch and then remove all of the files from this branch, so that it will just contain the documentation pages.
It's important to have an empty file in the root directory named .nojekyll. The existence of this file tells GitLab Pages not to run the published files through Jekyll, 
since Jekyll will discard any file that begins with _. 

.. note::

    The cWB documentation repository already has a `gl-pages` branch, so, normally you should skip this first step.

======================================
Building and pushing the documentation
======================================

The documentation should built from the source code on a regular branch and installed into the ``gl-pages`` branch. Since git cannot have two branches checked out simultaneously, you need to check out another copy of the repository with the ``gl-pages`` branch inside your cWB source repository. Do this will the following commands.

.. code-block:: bash

    cd /path/to/your/repo/cWB/documentation
    git clone -b gl-pages git@gitlab.com:gwburst/documentation.git _gl-pages

Now flush the contents of this directory. We do this, as the documentation is
not really under version control in the ``gl-pages`` branch. We just use this
branch to publish to GitLab pages. Run the commands (only if you want to cleanup outdated files)

.. code-block:: bash

    cd _gl-pages
    git rm -rf latest
    git commit -a -m "flush documentation"
    cd ..

The last ``cd`` command should put you back at the top level of your cWB
source directory. To build the documentation into the ``_gl-pages`` directory,
run the command

.. code-block:: bash

    make -f Makefile.gl_pages html
    make -f Makefile.gl_pages doxygen
    
This will build the documentation in the second repository that you created called ``_gl-pages`` under the directory ``latest/``. To push these changes up to GitLab

.. code-block:: bash

    cd _gl-pages
    git add --all
    git commit -a -m "documentation update"
    git push

The documentation will then be available under your GitLab pages at ``https://gwburst.gitlab.io/documentation/latest/html/``.

.. danger::

    Be careful with the ``git rm -rf *`` command as if you run it in the wrong
    directory you can delete the contents of your git repository. If you do
    this by accident, you can use ``git reset`` to undo the commit.