Introduction

This is the repository for the public ATLAS software documentation pages deployed at https://atlas-software.docs.cern.ch.

How to contribute

All changes or additions to the contents of these pages should be made via merge requests to this repository.

Do not fork this repository. Instead, make a clone of the respository locally, create a local feature branch with the relevant modifications/additions, and then generate a merge request. The instructions below give a step-by-step guide for this.

The content is in the form of MarkDown files; generally these are what contributors will edit or create. You can easily launch a local installation of the pages so you can review the content in a static form before pushing to the repository. Instructions on this are also given below.

As an alternative, if you are confident in your GitLab and MarkDown skills, simply use the WebIDE, there's even a preview button on the top right.

Getting started

• First clone this repository and add it as a remote so you can pull in updates from the main repository(only needed once)

  git clone ssh://git@gitlab.cern.ch:7999/atlas/software-docs/atlas-software-docs.git
  cd atlas-software-docs

• Fetch the latest updates (do this each time you want to make a change and whenever you need to rebase)

  git fetch

• Create a feature branch for your updates

  git checkout -b <name of your feature branch> origin/main

• Make your edits locally. You can preview the pages in (e.g.) an editor such as VSCode, or view via a local installation of the static pages (see below).

Creating a merge request

• When you're ready to push your changes and create a merge request:

  git add <changed files>
  git commit

  Make relevant commit notes and then

  git push -u origin <name of your branch>

  You'll then be invited to create a merge request by following the link, which you should do. Once the CI has finished running you can preview the site by clicking on the View App button.

Fixing spelling mistakes

The CI runs a spellchecker. In case there are warnings, follow these steps to fix them:

1. If it is a genuine spelling mistake correct it. Also check correct capitalization, e.g. TWiki vs Twiki, url vs URL, xml vs XML.

2. Use back-quotes and code blocks for code, e.g. ISystematicsTool.

3. As as last resort add the word to the dictionary in tests/aspell.atlassw.en.pws.

Previewing the pages locally

Installation

To get started, clone the repository locally as described above, then do:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Running the server

Each time you need to do:

source .venv/bin/activate
mkdocs serve --open

This will build the web-page and then open a browser window on your local machine (or manually navigate to http://127.0.0.1:8000).

Spellchecker

To run the spellchecker locally, you can run the following command in your virtual environment:

python -m pyspelling -j4

This requires that aspell is installed locally (e.g. apt install aspell aspell-en).

Site Description

This site makes use of a few MkDocs markdown extensions, which you can see under markdown_extensions: in the mkdocs.yml file, and the macros plugin. This plugin allows a lot more complicated behaviour than base MkDocs, and also reads in the variables file.

We strongly suggest you read about MkDocs Material as well, as it is the theme used here and has a lot of powerful features (e.g. Admonitions really simplify some of the more complicated markdown we had before)

Staging area

Each merge request is deployed into a staging area using GitLab Pages parallel deployments. These paralell deployments expire after a configurable time defined in .gitlab-ci.yml or after the merge request has been merged. The currently active deployments can be seen under Deploy - Pages or Operate - Environments.

Migration

For tips about the migration of the ATLAS software documentation from Jekyll to MkDocs, please have a look at the Migration document.