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).

General guidelines

Please abide by the following guidelines when adding new material to the site.

Location of source material

• If you start a new topic, put the relevant pages in a directory with a logical name, and select the location in the menu structure via the top-level mkdocs.yml configuration file.
• Directories and files should have short and logical names, and if multiple strings are used they should be separated by a hyphen, e.g. software-infrastructure not SoftwareInfrastructure etc.

Internal links, locations and data

Links to other pages within this site should use the following: [Link text](/path/to/page.md). Omit the docs head directory. Don't add the domain name to internal links. Files in the same directory can just be pointed at directly with no path: [Link text](page.md)

Make use of pre-defined data and locations where possible. For instance:

• Links to the analysis software tutorial which are still on the legacy site: {{locations.analysisSWTutorial}}
• GitLab: {{data.athena_git_url}}/-/tree/... or {{data.athena_git_url}}/-/blob/...

These variables are defined in variables.yaml.

New variables should have a meaningful name based on the topic they discuss. For example, if a topic discusses remote proxy login, it should be named

locations.remote_proxy_login

or similar.

Headings

Each page can have only one top level heading (# Title) which should resemble the name on the menu. All other headings below it should be ## or lower. Capitalise the first word of the title and all words within the title (except articles, prepositions and conjunctions).

Quoting code snippets from GitLab

If you want to include a block of code from GitLab, don't copy-and-paste it but instead quote it directly, e.g.:

```python
--8<-- "{{data.athena_git_url}}/-/raw/main/Control/AthenaExamples/AthExHiveAthenaPool/python/WriteHiveDataObjConfig.py"
```

In this way the quoted code will update as the code on GitLab is updated.

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.