This repository contains user-level documentation for the VSC infrastructure. It is deployed on ReadTheDocs.

When a commit is done on the repository's master branch, the documentation is rebuilt automatically on ReadTheDocs, and is immediately live. Hence you may prefer to work on a branch for major updates.

You will need to clone the repository, i.e.,

$ git clone [email protected]:hpcleuven/VscDocumentation.git
$ cd VscDocumentation
$ git fetch origin development:development

Your life will be substantially easier if you can preview your changes locally. A conda environment has be defined to install all the required software

Downloads and installation instructions for Miniconda can be found on conda's website.

The YAML environment description file is sphinx.yml. The environment can be created using

$ conda env create -f environment.yml

Feel free to open issues to get fixes or improvements on the agenda. To get an overview of work that is planned or in progress, check out the project overview.

The sphinx environment can be activated by

$ source activate sphinx

Do not make changes in the master or development branch directly, but create feature/bugfix branches as required, e.g.,

$ git checkout development
$ git checkout -b feature/new_stuff

Note that at any given time, we should be able to merge the development branch into the master branch, and rebuild the documentation, hence the development branch should always be in a sane state.

Exception on feature/bugfix branches: use common sense, to fix a simple typo, it is likely better to do that directly in the development branch, and merge that immediately into master.

The repository contains a make file that has a target to run the sphinx server. The latter will monitor the source directory for changes, and serve the documentation to a web browser that is opened automatically.

$ make web

You can now edit the content to your heart's content, making commits to your feature branch as you go. You can push your feature branch to the Github repository whenever you like.

$ git push origin feature/new_stuff

When you are done, create a pull request on GitHub. For consistency, do the pull request to the development branch, not the master branch.

For major changes, it is good practice to ask others to review your pull request. Although this policy is encouraged, it is not enforced.

Once the pull request has been merged, the branch will be deleted from GitHub. For your own convenience, it is probably easiest to pull the master and development branches from GitHub, and remove the local feature branch, e.g.,

$ git checkout master
$ git pull
$ git checkout development
$ git pull origin development
$ git branch -d feature/new_stuff

1. source: directory containing the source to be rendered into HTML (e.g., rST and PNG files).
2. images: directory containing source documents for images (e.g., ODG files).
3. Makefile & make.bat: make files to render the documentation, and run a local web server.
4. sphinx.yml: conda environment definition.

The other files and directories are part of the migration, and may be removed at some later stage.

Note that ReadTheDocs has a very convenient feature. It lets you copy an URL to a (sub)section of the documentation to make it easy to refer via email. Simply copy the link represented by the paragraph icon that appears next to the (sub)section title when you hover near it.