From f6d6e6dbf8595a378bfac28161ae0d5e7c6ab606 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 21 Mar 2025 13:44:05 +0100 Subject: [PATCH 1/7] Add basic style guide --- STYLE.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 STYLE.md diff --git a/STYLE.md b/STYLE.md new file mode 100644 index 00000000..80246266 --- /dev/null +++ b/STYLE.md @@ -0,0 +1,48 @@ +# Style Guide + +This guide contains general guidelines for how to format and present documentation in this repository. +They should be followed for most cases, but as a guideline it can be broken, _with good reason_. + +The documentation is written using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). + +## General Formatting + +- Format paragraphs with one sentence per line for easier diffs. +- Leave a space before and after headings. + +## Headings are Written in Title Case + +Use [title case](https://en.wikipedia.org/wiki/Letter_case#Title_case) for headings, meaning all words are capitalized except for minor words. + +## Avoid Nesting Headings too Deep + +Nesting headings up to three levels is generally ok. + +## Unordered and Ordered Lists + +Write lists as proper sentences. +Separate the items simply with commas if each item is simple, or make each item a full sentence if the items are longer and contain multiple sentences. + +1. The first item can look like this, +2. The second like this, and +3. The third item like this. + +## Using Admonitions + +Aim to include examples, notes, warnings using [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) whenever appropriate. +They stand out better from the main text, and can be collapsed by default if needed. + +!!! example "Example one" + This is an example. + The title of the example uses [sentence case](https://en.wikipedia.org/wiki/Letter_case#Sentence_case). + +??? note "Collapsed note" + This note is collapsed, because it uses `???`. + +[](){#ref-style-references} +## References + +Add references to headings to allow easier cross-referencing from other sections. +Prefix the reference name with `ref-`, followed by at least one level of identifier for the page itself. +Finally, add an identifier for the heading itself. +[This section][ref-style-references] uses the identifier `ref-style-references`. From 99fa0bac83e27756fcc4640663efafa9a43cb2f7 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 21 Mar 2025 15:30:23 +0100 Subject: [PATCH 2/7] Move style guide to contributing section --- STYLE.md | 48 -------------------------------------- docs/contributing/index.md | 47 +++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 48 deletions(-) delete mode 100644 STYLE.md diff --git a/STYLE.md b/STYLE.md deleted file mode 100644 index 80246266..00000000 --- a/STYLE.md +++ /dev/null @@ -1,48 +0,0 @@ -# Style Guide - -This guide contains general guidelines for how to format and present documentation in this repository. -They should be followed for most cases, but as a guideline it can be broken, _with good reason_. - -The documentation is written using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). - -## General Formatting - -- Format paragraphs with one sentence per line for easier diffs. -- Leave a space before and after headings. - -## Headings are Written in Title Case - -Use [title case](https://en.wikipedia.org/wiki/Letter_case#Title_case) for headings, meaning all words are capitalized except for minor words. - -## Avoid Nesting Headings too Deep - -Nesting headings up to three levels is generally ok. - -## Unordered and Ordered Lists - -Write lists as proper sentences. -Separate the items simply with commas if each item is simple, or make each item a full sentence if the items are longer and contain multiple sentences. - -1. The first item can look like this, -2. The second like this, and -3. The third item like this. - -## Using Admonitions - -Aim to include examples, notes, warnings using [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) whenever appropriate. -They stand out better from the main text, and can be collapsed by default if needed. - -!!! example "Example one" - This is an example. - The title of the example uses [sentence case](https://en.wikipedia.org/wiki/Letter_case#Sentence_case). - -??? note "Collapsed note" - This note is collapsed, because it uses `???`. - -[](){#ref-style-references} -## References - -Add references to headings to allow easier cross-referencing from other sections. -Prefix the reference name with `ref-`, followed by at least one level of identifier for the page itself. -Finally, add an identifier for the heading itself. -[This section][ref-style-references] uses the identifier `ref-style-references`. diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 680bc052..1960ab82 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -192,3 +192,50 @@ Once your changes are ready, click on the "Commit changes..." button in the top * if the change is small and you are CSCS staff, you can merge the PR immediately * all other changes can be + +## Style Guide + +This section contains general guidelines for how to format and present documentation in this repository. +They should be followed for most cases, but as a guideline it can be broken, _with good reason_. + +### General Formatting + +- Format paragraphs with one sentence per line for easier diffs. +- Leave a space before and after headings. + +### Headings are Written in Title Case + +Use [title case](https://en.wikipedia.org/wiki/Letter_case#Title_case) for headings, meaning all words are capitalized except for minor words. + +### Avoid Nesting Headings too Deep + +Nesting headings up to three levels is generally ok. + +### Unordered and Ordered Lists + +Write lists as proper sentences. +Separate the items simply with commas if each item is simple, or make each item a full sentence if the items are longer and contain multiple sentences. + +1. The first item can look like this, +2. The second like this, and +3. The third item like this. + +### Using Admonitions + +Aim to include examples, notes, warnings using [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) whenever appropriate. +They stand out better from the main text, and can be collapsed by default if needed. + +!!! example "Example one" + This is an example. + The title of the example uses [sentence case](https://en.wikipedia.org/wiki/Letter_case#Sentence_case). + +??? note "Collapsed note" + This note is collapsed, because it uses `???`. + +[](){#ref-style-references} +### References + +Add references to headings to allow easier cross-referencing from other sections. +Prefix the reference name with `ref-`, followed by at least one level of identifier for the page itself. +Finally, add an identifier for the heading itself. +[This section][ref-style-references] uses the identifier `ref-style-references`. From f1f6bfadad1de12bc6c7474586599865f3775041 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 21 Mar 2025 16:53:07 +0100 Subject: [PATCH 3/7] Remove general formatting section from contributing.md Replaced by more detailed formatting section --- docs/contributing/index.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 1960ab82..3b5d6e82 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -198,11 +198,6 @@ Once your changes are ready, click on the "Commit changes..." button in the top This section contains general guidelines for how to format and present documentation in this repository. They should be followed for most cases, but as a guideline it can be broken, _with good reason_. -### General Formatting - -- Format paragraphs with one sentence per line for easier diffs. -- Leave a space before and after headings. - ### Headings are Written in Title Case Use [title case](https://en.wikipedia.org/wiki/Letter_case#Title_case) for headings, meaning all words are capitalized except for minor words. From fccd00f24d6fabaa9ee3029389394952c9672078 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 21 Mar 2025 16:53:26 +0100 Subject: [PATCH 4/7] Use sentence case in list --- docs/contributing/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 3b5d6e82..fe8d1aa1 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -212,8 +212,8 @@ Write lists as proper sentences. Separate the items simply with commas if each item is simple, or make each item a full sentence if the items are longer and contain multiple sentences. 1. The first item can look like this, -2. The second like this, and -3. The third item like this. +2. the second like this, and +3. the third item like this. ### Using Admonitions From 6a5a6a71ae82b479ecd46cb3497aba33580b6499 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 21 Mar 2025 17:52:48 +0100 Subject: [PATCH 5/7] Update docs/contributing/index.md Co-authored-by: Rocco Meli --- docs/contributing/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index fe8d1aa1..c4c6fcf6 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -226,6 +226,8 @@ They stand out better from the main text, and can be collapsed by default if nee ??? note "Collapsed note" This note is collapsed, because it uses `???`. + +If an admonition is collapsed by default, it should have a title. [](){#ref-style-references} ### References From 4b7a28d2c5d44e29381b94e5ee7f4ebb1e9e7fd3 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 21 Mar 2025 17:54:00 +0100 Subject: [PATCH 6/7] Remove references section from style guide --- docs/contributing/index.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index c4c6fcf6..61c02d5a 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -228,11 +228,3 @@ They stand out better from the main text, and can be collapsed by default if nee This note is collapsed, because it uses `???`. If an admonition is collapsed by default, it should have a title. - -[](){#ref-style-references} -### References - -Add references to headings to allow easier cross-referencing from other sections. -Prefix the reference name with `ref-`, followed by at least one level of identifier for the page itself. -Finally, add an identifier for the heading itself. -[This section][ref-style-references] uses the identifier `ref-style-references`. From dce66c6957cc6d9cbf08bd20eea423c99c824418 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 21 Mar 2025 18:00:57 +0100 Subject: [PATCH 7/7] Use sentence case in contributing.md and style guide for headings --- docs/contributing/index.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 61c02d5a..7838a972 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -3,7 +3,7 @@ This documentation is developed using the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) framework, and the source code for the docs is publicly available on [GitHub](https://github.com/eth-cscs/cscs-docs). This means that everybody, CSCS staff and the CSCS user community can contribute to the documentation. -## Getting Started +## Getting started We use the GitHub fork and pull request model for development: @@ -40,7 +40,7 @@ To build the docs in a `site` sub-directory: ```bash ./serve build ``` -## Review Process +## Review process Documentation is owned by everybody - so don't be afraid to jump in and make changes or fixes where you see that there is something missing or outdated. @@ -57,7 +57,7 @@ If you don't get a timely reply, ask the documentation owners for a review or fo ### Links -#### External Links +#### External links Links to external sites use the `[]()` syntax: @@ -71,7 +71,7 @@ Links to external sites use the `[]()` syntax: [The Spack repository](https://github.com/spack/spack) -#### Internal Links +#### Internal links !!! note The CI/CD pipeline will fail if it detects broken links in your draft documentation. @@ -124,7 +124,7 @@ Images are stored in the `docs/images` directory. !!! tip Do you need a screenshot, or can a text description also work? -### Text Formatting +### Text formatting Turn off automatic line breaks in your text editor, and stick to one sentence per line in paragraphs of text. @@ -169,7 +169,7 @@ This method defines a canonical represention of text, i.e. there is one and only * changing one line of text will not modify the surrounding lines (see example above) * git diffs and git history are easier to read. -### Frequently Asked Questions +### Frequently asked questions The documentation does not have a FAQ section, because questions are best answered by the documentation, not in a separate section. Integrating information into the main documentation requires some care to identify where the information needs to go, and edit the documentation around it. @@ -179,7 +179,7 @@ FAQ content, such as lists of most frequently encountered error messages, is sti If you want to add such content, create a section at the bottom of a topic page, for example this section on the [SSH documentation page][ref-ssh-faq]. -### Small Contributions +### Small contributions Small changes that only modify the contents of a single file, for example to fix some typos or add some clarifying detail to an example, it is possible to quickly create a pull request directly in the browser. @@ -193,20 +193,20 @@ Once your changes are ready, click on the "Commit changes..." button in the top * if the change is small and you are CSCS staff, you can merge the PR immediately * all other changes can be -## Style Guide +## Style guide This section contains general guidelines for how to format and present documentation in this repository. They should be followed for most cases, but as a guideline it can be broken, _with good reason_. -### Headings are Written in Title Case +### Headings are written in sentence case -Use [title case](https://en.wikipedia.org/wiki/Letter_case#Title_case) for headings, meaning all words are capitalized except for minor words. +Use [title case](https://en.wikipedia.org/wiki/Letter_case#Sentence_case) for headings, meaning all words are capitalized except for minor words. -### Avoid Nesting Headings too Deep +### Avoid nesting headings too deep Nesting headings up to three levels is generally ok. -### Unordered and Ordered Lists +### Lists Write lists as proper sentences. Separate the items simply with commas if each item is simple, or make each item a full sentence if the items are longer and contain multiple sentences. @@ -215,7 +215,7 @@ Separate the items simply with commas if each item is simple, or make each item 2. the second like this, and 3. the third item like this. -### Using Admonitions +### Using admonitions Aim to include examples, notes, warnings using [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) whenever appropriate. They stand out better from the main text, and can be collapsed by default if needed.