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:

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.

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)

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

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

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.