Building Documentation for GitLab Pages¶
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.
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.