Skip to content

Latest commit

 

History

History
310 lines (244 loc) · 24.4 KB

CONTRIBUTING.md

File metadata and controls

310 lines (244 loc) · 24.4 KB
Raw

HPC-community-docs

Contributing guidelines

Welcome to the University of Bristol Advanced Computing Research Centre (ACRC) HPC community documentation project! This project provides a space for HPC users at the University of Bristol to publish domain-specific information on how to effectively use HPC facilities managed by the ACRC at the University of Bristol.

Thank you for your interest in contributing! This document collects useful information to assist you through the process of creating and submitting your contribution.

CONTENTS

Key links

  • Documentation website: HPC community documentation deployed as HTML website
  • README.md: general information about the repository and documentation project
  • LICENSE.md: licenses for content in the repository
  • Issues: the place to raise and discuss bugs, issues, enhancements
  • humans.txt: information about project contributors

In this repository

The HPC-community-docs repository contains

  • Documentation source files in MyST Markdown (reStructuredText is also supported)
  • Sphinx project files for running and configuring the documentation build process
  • A Conda environment file specifying the packages required to build the documentation

Building the documentation

Building the documentation generates the documentation in a user-friendly output format, such as a HTML website or PDF file, from the source files.

Setting up the build system

To build the documentation on your own computer, you must install Sphinx and some other supporting packages.

The simplest way to do this is to create a Conda environment using the provided environment.yml file. This will create an isolated software environment containing all the packages required to build the documentation.

1. Install the Conda package manager

Creating a Conda environment requires the Conda package manager. If the conda command is already available on your computer (e.g. from an installation of the Anaconda distribution), you can skip to the next step. Otherwise, you can install conda by downloading and installing Miniconda3 for your operating system, following the instructions in the Conda documentation.

2. Clone the repository

Create a clone of this repository on your computer. This can be done using Git on the command line, e.g. running the following command

git clone https://github.com/ACRC/HPC-community-docs.git

will create a clone of the repository in the current directory. Alternatively, use an IDE like VSCode or a Git GUI client such as GitHub Desktop to clone the repository.

NOTE: If git clone fails with an error indicating that the git command cannot be found, then you may need to install Git on your computer. For instructions for installing Git on Linux, macOS, or Windows, see the section "Installing Git" in the free online Pro Git book.

3. Create a Conda environment

Once the repository is cloned, start a command line session and change to the repository directory (HPC-community-docs). A conda environment file environment.yml should be present in the directory.

Create the conda environment using the command

conda env create --file environment.yml

This will create a new conda environment called HPC-community-docs-env, with Sphinx and supporting packages installed.

NOTE: If you are using Windows and conda commands fail with an error indicating that the conda command cannot be found, you may need to launch your command line session using the "Anaconda Prompt" or "Anaconda PowerShell Prompt" Start menu items. Launching the command line session in this way ensures that the session environment is set up correctly to use conda.

4. Check the environment

To check that the environment has been successfully created, activate it

conda activate HPC-community-docs-env

Your command line prompt should now be prefixed by the environment name in brackets: (HPC-community-docs-env).

With HPC-community-docs-env activated, check that Sphinx is installed by running

sphinx-build --version

If Sphinx has been installed in the environment, the command should output the version number, e.g.

sphinx-build 4.4.0

When you have finished working with the environment, you can close it using

conda deactivate

Running the build process

After cloning the repository and creating the HPC-community-docs-env Conda environment, you should be able to build the documentation on your computer. The following instructions describe how to build the documentation into a HTML website, viewable in a web browser.

1. Activate the environment

Start a command line session, change to the repository directory (HPC-community-docs-env) and activate the environment using

conda activate HPC-community-docs-env

2. Generate the documentation

Run the command

make html

This will build HTML pages based on the source documents in the source directory, placing the result in the build/html directory.

NOTE If make html fails with an error indicating that the make command cannot be found, then the build can be run using the command

sphinx-build -M html source build

(the sphinx-build command is invoked by make behind the scenes).

3. View the result

To view the result of the build process, open build/html/index.html in a web browser. If the build process was successful, the browser should display a browsable website containing formatted text from the source files in source.

It is also possible to build the documentation in other formats, e.g. PDF (see the documentation for sphinx-build for a list of common build formats). Since the HPC community documentation is intended to be built as a website, we will only consider the HTML builder here.

NOTE The generated documentation can be opened directly in your default browser from a command line session. From the repository directory, on macOS use

open build/html/index.html

and on Windows PowerShell

Invoke-Item .\build\html\index.html

For Linux,

xdg-open build/html/index.html

may work if your distribution provides it.

Modifying and adding to the documentation

Useful resources

While editing and adding to the documentation, the following resources may be useful to have at hand:

Workflow

A typical workflow for working on the documentation is to repeat the following three steps

  1. Edit the files in the source/ directory (add, remove, or change content)
  2. Build the documentation
  3. Review the result in the build/html/ directory

If the build step fails (e.g. due to a syntax error in the source files), then Sphinx will generally output a meaningful error message to the command line session. After correcting the error, re-run the build process (make html) and continue with the edit-build-review cycle.

Editing existing pages and adding new pages

To work on an existing page, simply open a source file (usually ending .md or .rst) in the source/ directory in a text editor, make changes, and save your changes.

To add a new page to the documentation, create a new source file in the source/ directory and add some text to it.

To include content in a new page in the table of contents for the documentation, add the document name of the file to the toctree directive in the root document, source/index.md. Alternatively, you can add the document name to a toctree in another document that is referenced (directly or indirectly) from the toctree in the root document.

When the documentation is rebuilt, HTML generated from the edited and/or newly added pages will be included in the result in the build/ directory.

Using MyST Markdown

Source documents for the HPC community documentation project can be written using MyST Markdown (.md) or reStructuredText (.rst). These are both lightweight markup languages. We recommend using MyST Markdown, unless you have a good reason to use reStructuredText (e.g. you are starting from an existing .rst file). MyST Markdown extends the CommonMark Markdown specification, to add the capabilities of reStructuredText, while retaining the clean and readable syntax of Markdown.

In addition to the MyST Markdown documentation, Jupyter Book's MyST Markdown cheat sheet is a useful quick reference guide for common syntax in technical documentation.

The MyST Markdown documentation does not cover all the Sphinx functionality that can be used in MyST Markdown, but provides instructions on translating from reStructuredText syntax (Sphinx's native markup language) to MyST syntax. Sphinx/reStructuredText roles and directives documented elsewhere (e.g. in the Sphinx documentation) can be translated for use in MyST documentation using these instructions.

To simplify editing the documentation, it is advisable to use a text editor or IDE that provides Markdown support (for example syntax highlighting and preview). Many text editors and IDEs provide Markdown support, or have extensions that add this, so you may already have one installed. If you do not already have a suitable editor, Visual Studio Code is a good option which supports Markdown editing and preview. There is also a MyST Markdown extension for Visual Studio Code (developed by the Executable Book Project) that adds additional MyST-Markdown-specific capabilities to the editor.

Contributing changes to the repository

Licensing

All text contributions to the documentation project will be licensed under a Creative Commons Attribution-ShareAlike 4.0 license. Code snippets and software included in the documentation are published under a MIT license. See LICENSE.md for full details.

Before making your contribution, please ensure

  • you are authorized to apply the licenses in LICENSE.md to your contribution
  • you are happy for your contribution to be published under the licenses in LICENSE.md

Workflow

The HPC community documentation project uses the fork and pull model for collaborative development (also known as the forking workflow). To develop and contribute changes to the documentation:

  • Create a fork of the HPC-community-docs GitHub repository on GitHub
  • Clone the forked repository onto your local machine
  • Create a feature branch in the forked repository
  • Commit additions and changes to the feature branch in the forked repository
  • Push the updated feature branch to the forked repository
  • When the changes in the feature branch are ready to contribute, create a pull request from the fork which requests merging changes from the feature branch into main in the upstream repository
  • The pull request will be reviewed by maintainers, and changes/refinements may be requested
  • Once the pull request is approved by reviewers, it will be merged into main

Additional contributions can be made from the same fork, by creating a new feature branch in the fork.

To keep your fork and feature branches up-to-date, it is recommended to regularly sync the fork with the upstream (official) repository. Keeping the main branch in your fork synchronised with the main branch in the upstream repository ensures contributions from others to the upstream repository are incorporated into the fork. Merging changes from upstream main into active feature branches on your fork helps avoid complex merge conflicts arising when creating a pull request.

Documentation example

An example collection of source files showing the recommended structure of contributed documentation for a research domain and domain-specific software package can be found in source/example-domain/. Please feel free to use this example as a starting point for your own contributions.

Deployment of the documentation

The HPC community documentation project uses GitHub Actions to automate building of the documentation into a HTML website and publishing (deployment) of the website. The website is published using GitHub Pages at https://acrc.github.io/HPC-community-docs/.

The GitHub Actions workflow for building and deploying the documentation is defined in .github/workflows/main.yml. The workflow is run on a GitHub-hosted virtual machine ("runner") whenever commits are pushed to the repository (to any branch) and when a pull request is opened, updated (with new commits), or reopened. When run, the workflow will always attempt to build the documentation, but will only deploy the built website to GitHub Pages for commits to the main branch on the official repository.

For a commit pushed to a branch, the workflow will run using the documentation source files present in the pushed commit. For a pull request, the workflow will run using the source files as they would be if the pull request was merged (on the refs/pull/prNumber/merge branch).

Information about current and past workflow runs on the official repository can be viewed in the Actions tab on the repository GitHub page.

Actions on forks

When you create a fork of the HPC-community-docs GitHub repository, GitHub Actions will initially be disabled on the fork. The fork's Actions tab on GitHub will display a message indicating that workflows are not being run on the forked repository and a button that enables workflows.

Once Actions are enabled on a fork of the HPC-community-docs repository, the workflow will run in the context of the fork whenever commits are pushed to a branch on that fork.

The workflow will build the documentation, but will not deploy the built website to GitHub Pages, even if commits are pushed to the main branch of the fork. This is because the deployment job in the workflow will only run on the main branch of the official repository.

GitHub Pages is also disabled when creating a fork (see the "Pages" section in the forked repository settings). The official repository uses the root of the publishing-source branch as the publishing source for GitHub Pages rather than the default gh-pages branch. This avoids automatic activation of GitHub Pages when the official repository is forked.

Do not publish to GitHub Pages on forks!

Please do not deploy the built documentation to GitHub Pages on your forked version of the official repository!

A fork can be made to publish the documentation to the web by modifying the workflow file to allow deployment on any repository, or by manually committing the built HTML documentation files to the publishing source branch on the fork. Please do not do this.

We ask you not to publish the version of the documentation on a fork to avoid creating duplicates in search engine results and confusing readers. If a contributor's fork publishes documentation to https://username.github.io/HPC-community-docs/, then this will result in multiple versions of the HPC community documentation being publicly accessible. For readers of the documentation, it would be easy to accidentally find and use the version of the documentation published by a fork, rather than the version published from the official repository.

To ensure the canonical version of the HPC community documentation at https://acrc.github.io/HPC-community-docs/ is easily findable by users, please do not publish documentation you are working on in a fork to the web. If you need view the result of a build from an Actions workflow run, you can do this locally by downloading the a build artifact for the workflow run.

Downloading documentation build artifact

If you want to check the result of the documentation build job in a workflow run, you can download a zip archive containing the built HTML documentation for that specific workflow run. This can be downloaded by selecting the workflow run on the repository Actions tab, then selecting built-html-docs under "Artifacts". The built documentation can be viewed locally by decompressing the archive and opening index.html in a web browser, as described above (the archive contains the contents of the build/html/ directory created during the build process).

The artifact containing the built documentation can be downloaded for workflows run on pull requests. To access the workflow run page where the artifact can be downloaded from a pull request page, select "Details" next to the "Build HTML documentation" item in the list of checks.

Workflows on pull requests are run in the context of the base repository for the pull request (i.e. the repository into which the pull request would merge changes) and are also visible under the base repository's Actions tab. The built-html-docs artifact for a workflow running on a pull request to merge changes into the main branch of the official repository contains the built documentation as would be published on the web (upon merging the pull request).

Asking for help

For general queries related to the ACRC and ACRC HPC facilities, please contact the ACRC team directly.

If you need assistance with preparing a contribution to the HPC community documentation project, please contact James C. Womack (@jcwomack).