GitLab service scheduled maintenance on Monday, August 18th 2025 as of 07h00 Geneva time for a period of 3 hours. Further information under OTG0157026.
This is the repository for the **public** ATLAS software documentation pages deployed at https://atlas-software.docs.cern.ch.
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.
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.
**Do not fork this repository**. Instead, make a clone of the repository
locally, create a local feature branch with the relevant modifications or
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.
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.
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)
* First clone this repository and add it as a remote so you can pull in updates
* Fetch the latest updates (do this each time you want to make a change and whenever you need to rebase)
* Fetch the latest updates (do this each time you want to make a change and
whenever you need to rebase)
```shell
git fetch
```
...
...
@@ -29,7 +40,9 @@ As an alternative, if you are confident in your GitLab and MarkDown skills, simp
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](https://code.visualstudio.com/docs/languages/markdown#_markdown-preview), or view via a local installation of the static pages (see below).
* Make your edits locally. You can preview the pages in (e.g.) an editor such as
or view via a local installation of the static pages (see below).
### Creating a merge request
...
...
@@ -42,17 +55,21 @@ As an alternative, if you are confident in your GitLab and MarkDown skills, simp
```shell
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.
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:
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](tests/aspell.atlassw.en.pws).
3. As as last resort add the word to the dictionary in
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](http://127.0.0.1:8000)).
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](http://127.0.0.1:8000)).
### Spellchecker
To run the spellchecker locally, you can run the following command in your
...
...
@@ -88,21 +105,29 @@ 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.
* 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)`
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}}`
* 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](data/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
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
```
...
...
@@ -110,11 +135,15 @@ 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).
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.:
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
...
...
@@ -125,14 +154,29 @@ If you want to include a block of code from GitLab, don't copy-and-paste it but
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](https://www.mkdocs.org) markdown extensions, which you can see under `markdown_extensions:` in the [mkdocs.yml](mkdocs.yml) file, and the [macros](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) plugin. This plugin allows a lot more complicated behaviour than base MkDocs, and also reads in the [variables](data/variables.yaml) file.
We strongly suggest you read about [MkDocs Material](https://squidfunk.github.io/mkdocs-material/reference/) as well, as it is the theme used here and has a lot of powerful features (e.g. [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) really simplify some of the more complicated markdown we had before)
This site makes use of a few [MkDocs](https://www.mkdocs.org) markdown
extensions, which you can see under `markdown_extensions:` in the
[mkdocs.yml](mkdocs.yml) file, and the
[macros](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) plugin. This
plugin allows a lot more complicated behaviour than base MkDocs, and also reads
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](https://docs.gitlab.com/user/project/pages/parallel_deployments/). These paralell deployments expire after a configurable time defined in [.gitlab-ci.yml](.gitlab-ci.yml) or after the merge request has been merged. The currently active deployments can be seen under [Deploy - Pages](https://gitlab.cern.ch/atlas/software-docs/atlas-software-docs/pages) or [Operate - Environments](https://gitlab.cern.ch/atlas/software-docs/atlas-software-docs/-/environments).
Each merge request is deployed into a staging area using
