Contribute

This page describes the process of contributing to this documentation. There is a simple six step workflow described in the first section, and there are more detailed notes on each step in case you have issues.

Six steps to contribute documentation

  1. Clone the BCPU-documentation repository using git. Ideally you should clone this repository to NIRD, in the location /project/NS9039K/www/<user>/ where <user> is your personal directory (if you do not have one, create one with your name or username).

  2. Make changes or add files in the source (BCPU-documentation/source) directory.

  3. In the root directory (BCPU-documentation/) Call the command make github which will build html files into the build/ directory and automatically and copy them into the docs/ directory.

  4. Check your changes locally, before pushing them to GitHub.

  5. Add, commit and push your changes to GitHub.

  6. Check the published changes online (this can take a couple of minutes to update).

Cloning the GitHub repository

In order to clone the repository, you should run the command `git clone git@github.com:BjerknesCPU/BCPU-documentation.git which will produce a directory ‘BCPU-documentation/’ in the directory you are working in. You should clone this repository to NIRD, in the location /project/NS9039K/www/<user>/ where <user> is your personal directory (if you do not have one, create one with your name or username).

You only need to do this step the first time you modify the documentation.

For more on cloning, see this page.

If you have never used the organisational GitHub before, you may have to set up ssh keys.

If you have issues with this step, or with access to the GitHub repository, please contact our internal support.

Making changes to the source

The ‘source’ refers to the files that we write, and the ‘build’ refers to files that are generated from the source and displayed on the documentation site.

In this documentation, the source files are written in reStructuredText, which is a type of markup. Writing in this format, allows the build files (html) to be automatically generated from the source files, so we just have to worry about writing the source files, which are stored in the source/ directory.

Here is an introduction to reStructuredText but an easy way of getting started is to copy the format of existing .rst files in the source directory.

Create a new file with the extension .rst to add a new page to the documentation. You can create a new directory if you want a new category of documentation to organise your documentation within.

If you have added a new page to the documentation, you must add a link to it in the file index.rst. For example, the following text adds a link to the ‘contribute’ page in the ‘documentation’ category:

.. toctree::
  :maxdepth: 1
  :caption: Documentation

  documentation/contribute

Build the documentation

The documentation is built using Sphinx. In order to use Sphinx, you will need to load an environment which contains the library. On NIRD, this is our shared conda environment, which can be activated as follows:

$ source /opt/anaconda3/etc/profile.d/conda.sh
$ conda activate /projects/NS9039K/shared/python3env

The documentation is built by calling: make github in the root directory. This will use the files in the source/ directory to generate html files in the build/ directory. These are then automatically copied to the docs/ directory, which is where the documentation is read from for the website. Of course, these changes are not applied to our documentation website until we push back to GitHub, but you can have a look at your changes before you make them visible to everyone else (see next step).

Check your changes

Once you have run the make github command, the built files should be available for viewing in the docs/ directory. It is good practice to view these files in an HTML browser before pushing them to GitHub. If you have cloned the repository to NIRD in the /projects/NS9039K/www/<user> directory, then you can check your changes here.

Add, commit and push your changes

Use git add, git commit and git push to push your changes to the remote repository. Once you have done this, the online pages should automatically update after 1-2 minutes.