From eda9f8333153033719404cca74ff646a743c76f4 Mon Sep 17 00:00:00 2001
From: jcatmore <james.catmore@cern.ch>
Date: Mon, 31 Mar 2025 13:34:41 +0200
Subject: [PATCH 1/7] Updating contribution guide with general guidelines
This adds some general guidelines to the contribution guide README, in particular:
- where source md material should go
- using internal links, location/data variables
- headings
We may want to add more either now or later...
I realised as I was doing this that when we moved the trigger stuff to its own menu bar item, we didn't follow the convention and move the markdown source files out of the athena directory. If we want to be consistent we will need to do this.
---
README.md | 33 +++++++++++++++++++++++++++++++++
1 file changed, 33 insertions(+)
diff --git a/README.md b/README.md
index f79f9c9..cc32ea9 100644
--- a/README.md
+++ b/README.md
@@ -93,3 +93,36 @@ Each merge request is deployed into a staging area using [GitLab Pages parallel
## Migration
For tips about the migration of the ATLAS software documentation from Jekyll to MkDocs, please have a look at the [Migration](MIGRATION.md) document.
+
+## General guidelines
+
+Please abide by the following guidelines when adding new material to the site.
+
+### Location of source material
+
+Markdown source files should be located within the following directory structure:
+
+ * The top level directory immediatety underneath `docs` should correspond to the top menu bar under which the new page will sit (currently `athena`, `trigger`, `software-infrastructure`
+ * Lower directories should match the sidebar menu structure, so for example the material in the Athena configuration tutorial, which falls under the "Athena Configuration" sidebar item and then the "Configuration tutorial" submenu, is likewise in the following directory: `athena/configuration/tutorial`
+ * Directories should have a short and logical name, and if multiple strings are used they should be separated by a hyphen, e.g. `software-infrastructure` not `SoftwareInfrastructure`a etc.
+
+If you feel that a new menu bar item is needed, please discuss this in advance with the (software coordinators)[mailto:atlas-software-coordinators@cern.ch] as this is a major change to the layout of the site.
+
+### 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 use absolute links.
+
+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 [here](https://gitlab.cern.ch/atlas/software-docs/atlas-software-docs/-/blob/main/data/variables.yaml?ref_type=heads)
+
+If you want to add a new location variable, please follow the existing convention of leading the variable name with the top menu name followed by an underscore (e.g. `athena_`, `infrastructure_`).
+
+### 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.
+
+
--
GitLab
From 9e68661e52ffc3ddb1c364ccca0879996aaf8939 Mon Sep 17 00:00:00 2001
From: jcatmore <james.catmore@cern.ch>
Date: Mon, 31 Mar 2025 15:09:44 +0200
Subject: [PATCH 2/7] Amendments suggested by Frank
---
README.md | 25 ++++++++++++-------------
1 file changed, 12 insertions(+), 13 deletions(-)
diff --git a/README.md b/README.md
index cc32ea9..a169446 100644
--- a/README.md
+++ b/README.md
@@ -82,18 +82,6 @@ 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](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)
-
-### 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).
-
-
-## Migration
-For tips about the migration of the ATLAS software documentation from Jekyll to MkDocs, please have a look at the [Migration](MIGRATION.md) document.
-
## General guidelines
Please abide by the following guidelines when adding new material to the site.
@@ -110,7 +98,7 @@ If you feel that a new menu bar item is needed, please discuss this in advance w
### 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 use absolute links.
+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.
Make use of pre-defined data and locations where possible. For instance:
@@ -125,4 +113,15 @@ If you want to add a new location variable, please follow the existing conventio
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.
+## 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)
+
+### 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).
+
+
+## Migration
+For tips about the migration of the ATLAS software documentation from Jekyll to MkDocs, please have a look at the [Migration](MIGRATION.md) document.
--
GitLab
From d0b63861842a66b346d154113f19844e0dbd0cda Mon Sep 17 00:00:00 2001
From: jcatmore <james.catmore@cern.ch>
Date: Mon, 31 Mar 2025 16:42:40 +0200
Subject: [PATCH 3/7] Adding new guideline on links when MD source is in the
same directory
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index a169446..9d54c15 100644
--- a/README.md
+++ b/README.md
@@ -98,7 +98,7 @@ If you feel that a new menu bar item is needed, please discuss this in advance w
### 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.
+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:
--
GitLab
From 0ab2d53e02f863b9959bd5038abb5da4fe502315 Mon Sep 17 00:00:00 2001
From: jcatmore <james.catmore@cern.ch>
Date: Fri, 11 Apr 2025 12:27:14 +0200
Subject: [PATCH 4/7] Updates following discussion at software weekly meeting
---
README.md | 23 ++++++++++++++---------
1 file changed, 14 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
index 9d54c15..4fb577c 100644
--- a/README.md
+++ b/README.md
@@ -88,13 +88,8 @@ Please abide by the following guidelines when adding new material to the site.
### Location of source material
-Markdown source files should be located within the following directory structure:
-
- * The top level directory immediatety underneath `docs` should correspond to the top menu bar under which the new page will sit (currently `athena`, `trigger`, `software-infrastructure`
- * Lower directories should match the sidebar menu structure, so for example the material in the Athena configuration tutorial, which falls under the "Athena Configuration" sidebar item and then the "Configuration tutorial" submenu, is likewise in the following directory: `athena/configuration/tutorial`
- * Directories should have a short and logical name, and if multiple strings are used they should be separated by a hyphen, e.g. `software-infrastructure` not `SoftwareInfrastructure`a etc.
-
-If you feel that a new menu bar item is needed, please discuss this in advance with the (software coordinators)[mailto:atlas-software-coordinators@cern.ch] as this is a major change to the layout of the site.
+* 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
@@ -107,12 +102,22 @@ Make use of pre-defined data and locations where possible. For instance:
These variables are defined [here](https://gitlab.cern.ch/atlas/software-docs/atlas-software-docs/-/blob/main/data/variables.yaml?ref_type=heads)
-If you want to add a new location variable, please follow the existing convention of leading the variable name with the top menu name followed by an underscore (e.g. `athena_`, `infrastructure_`).
-
### 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.
+### 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](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.
--
GitLab
From fe5a6057e220c1811ec5ff6df0e71f6e8d2edd19 Mon Sep 17 00:00:00 2001
From: jcatmore <james.catmore@cern.ch>
Date: Fri, 11 Apr 2025 12:31:41 +0200
Subject: [PATCH 5/7] Adding comment on location variable names
---
README.md | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/README.md b/README.md
index 4fb577c..9b30249 100644
--- a/README.md
+++ b/README.md
@@ -102,6 +102,12 @@ Make use of pre-defined data and locations where possible. For instance:
These variables are defined [here](https://gitlab.cern.ch/atlas/software-docs/atlas-software-docs/-/blob/main/data/variables.yaml?ref_type=heads)
+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.
--
GitLab
From 402c4c1c9905aea075692d598726f6856a885439 Mon Sep 17 00:00:00 2001
From: jcatmore <james.catmore@cern.ch>
Date: Mon, 14 Apr 2025 10:13:38 +0200
Subject: [PATCH 6/7] Adding comment about capitalisation of titles
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 9b30249..bad9113 100644
--- a/README.md
+++ b/README.md
@@ -110,7 +110,7 @@ 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.
+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
--
GitLab
From 678900b25b87299c6dc9a1336ac728380165d62d Mon Sep 17 00:00:00 2001
From: James Catmore <james.catmore@cern.ch>
Date: Mon, 14 Apr 2025 08:18:55 +0000
Subject: [PATCH 7/7] Accepting suggestion
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index bad9113..0d191f5 100644
--- a/README.md
+++ b/README.md
@@ -100,7 +100,7 @@ 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 [here](https://gitlab.cern.ch/atlas/software-docs/atlas-software-docs/-/blob/main/data/variables.yaml?ref_type=heads)
+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
```
--
GitLab