Skip to content
Snippets Groups Projects
Commit af61a6f0 authored by Martin Schroschk's avatar Martin Schroschk
Browse files

Rename document and file

parent 7fcbe76b
No related branches found
No related tags found
2 merge requests!592Automated merge from preview to main,!554Content rules
Hide whitespace changes
Inline Side-by-side
Showing
with 195 additions and 170 deletions
doc.zih.tu-dresden.de/docs/contrib/content_rules.md → doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
+ 173
− 141
View file @ af61a6f0
......@@ -8,13 +8,20 @@
There is an exception to every rule.
## Motivation and Rationale
This page holds <del>rules</del> guide lines regarding the layout, content, and writing of this
documentation. The goals are to provide a comprehensive, consistent, up-to-date and well-written
documentation that is pure joy to read and use. It shall help to find answers and provide knowledge
instead of being the bottleneck and a great annoyance. Therefore, it need some guide lines which are
outlined in the following.
instead of being the bottleneck and a great annoyance. Therefore, we set up some guide lines which
are outlined in the following.
!!! tip
Following these guide lines when contributing speeds up the review process. Furthermore, your
changes will not be blocked by the automatic checks implementened in the CI pipeline.
## Responsibility And License
## Responsibility and License
This documentation and the repository have two licenses (cf. [Legal Notice](../legal_notice.md)):
......@@ -32,27 +39,45 @@ If you are in doubt, please contact us either via
[GitLab Issue](https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium/-/issues)
or via [Email](mailto:hpcsupport@zih.tu-dresden.de).
## Quick Overview
* All documentation is written in [Markdown](#markdown).
* Type spaces (not tabs) both in Markdown files and in `mkdocs.yml`.
* Respect the line limit of 100 characters (except for links).
* Do not add large binary files or high resolution images to the repository (cf.
[adding images and attachments](#grapics-and-attachments)).
* [Admonitions](#admonitions) may be actively used for longer code examples, warnings, tips,
important information etc.
* Respect the [writing style](#writing-style) and the rules for
[spelling and technical wording](#spelling-and-technical-wording).
* For code blocks:
* Use [syntax highlighting and appropriate prompts](#code-blocks-and-command-prompts).
* Respect [data privacy](#data-privacy-and-generic-names).
* Stick to the [rules on optional and required arguments](#unix-rules).
## Pages Structure and New Page
The pages structure is defined in the configuration file `mkdocs.yaml`:
The documentation and pages structure is defined in the configuration file
[mkdocs.yml](https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium/-/blob/main/doc.zih.tu-dresden.de/mkdocs.yml):
```Bash
nav:
- Home: index.md
- Application for Login and Resources:
- Overview: application/overview.md
- Terms: application/terms_of_use.md
- Terms of Use: application/terms_of_use.md
- Request for Resources: application/request_for_resources.md
- Project Request Form: application/project_request_form.md
- Project Management: application/project_management.md
- Acknowledgement: application/acknowledgement.md
- Access to ZIH Systems:
- Overview: access/overview.md
[...]
```
Follow these two steps to add a new page to the documentation:
Follow these two steps to **add a new page** to the documentation:
1. Create a new markdown file under `docs/subdir/file_name.md` and put the documentation inside.
1. Create a new Markdown file under `docs/subdir/file_name.md` and put the documentation inside.
The sub-directory and file name should follow the pattern `fancy_title_and_more.md`.
1. Add `subdir/file_name.md` to the configuration file `mkdocs.yml` by updating the navigation
section. Yes, the order of files is crucial and defines the structure of the content. Thus,
......@@ -63,25 +88,62 @@ the documentation structure.
## Markdown
All this documentation is written in markdown. Please keep things simple, i.e., avoid using fancy
markdown dialects.
All documentation is written in Markdown. Please keep things simple, i.e., avoid using fancy
Markdown dialects.
### Brief How-To on Markdown
| Purpose | Markdown | Rendered HTML |
|---|---|---|
| Bold text | `**Bold Text**` | **Bold Text** |
| Italic text | `*Italic Text*` | *Italic Text* |
| Headings | `# Level 1`, `## Level 2`, `### Level 3`, ... | |
| External link | `[website of TU Dresden](https://tu-dresden.de)` | [website of TU Dresden](https://tu-dresden.de) |
| Internal link | `[Slurm page](../jobs_and_resources/slurm.md)` | [Slurm page](../jobs_and_resources/slurm.md)|
| Internal link to section | `[section on batch jobs](../jobs_and_resources/slurm.md#batch-jobs)` | [section on batch jobs](../jobs_and_resources/slurm.md#batch-jobs) |
??? node "Lists and enumerations"
```markdown
* First list item
* Second list item
* Nested item
* Another list item
```
* First list item
* Second list item
* Nested item
* Another list item
```markdown
1. First list item
1. Second list item
1. Nested item
1. Another list item
```
* [Cheat Sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
* [Style Guide](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md)
1. First list item
1. Second list item
1. Nested item
1. Another list item
For further reading, we recommand this
[Cheat Sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) an Markdown.
### Graphics and Attachments
Images and graphics are an important part of technical documentation. This also holds for this HPC
Images and graphics are an important part of every technical documentation, They are use used to
provide a more detailes or further outline a certain process and topic. This also holds for this HPC
compendium. Thus, we encourage you to add images and graphics for illustration purposes.
Attachments may be used to provide a more detailed documentation or further outline a certain
process and topic.
All images, graphics and attachments are stored in the `misc` subdirectory of the corresponding
section.
All graphics and attachments are saved within `misc` directory of the respective sub directory in
`docs`.
!!! example "Syntax"
The syntax to insert a graphic or attachment into a page is
```markdown
![Alternative text](misc/<graphics_file>)
{: align="center"}
......@@ -89,13 +151,15 @@ section.
The attribute `align` is optional. By default, graphics are left aligned. **Note:** It is crucial to
have `{: align="center"}` on a new line.
It is possible to add captions for tables and figures using `{: summary="This is a table caption"}`.
The `summary` and `align` parameters can be combined as well:
`{: summary="This is a table caption" align="top"}`.
!!! warning
Do not add large binary files or high resolution images to the repository. See this valuable
document for [image optimization](https://web.dev/fast/#optimize-your-images).
### Admonitions
[Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/), also known as
......@@ -103,19 +167,21 @@ call-outs, may be actively used to highlight examples, warnings, tips, important
Admonitions are an excellent choice for including side content without significantly interrupting
the document flow.
Several different admonitions are available within the material theme, e.g., `note`, `info`,
`example`, `tip`, `warning` and `cite`.
Please refer to the
Several different admonitions are available within the used
[material theme](https://squidfunk.github.io/mkdocs-material/), e.g., `note`, `info`, `example`,
`tip`, `warning` and `cite`. Please refer to the
[documentation page](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types)
for a comprehensive overview.
All admonitions blocks start with `!!! <type>` and the following content block is indented by
(exactly) four spaces.
!!! example "Syntax"
All admonitions blocks start with `!!! <type>` and the following content block is indented by
(exactly) four spaces.
If no title is provided, the title corresponds to the admonition type.
```markdown
!!! note
!!! note "Descriptive title"
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
......@@ -128,20 +194,6 @@ Admonitions can be made foldable by using `???` instead of `!!!`. A small toggle
is displayed. The block is open by default if `???+` is used. Long code examples should be folded by
default.
#### Title
The title corresponds to the admonition type. However, the title of an admonition can be changed for
further decoration by providing the desired title as quoted string after the type qualifier.
```markdown
!!! note "Random title"
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
vero eos et accusam et justo duo dolores et ea rebum.
```
## Writing Style
* Avoid using tabs both in markdown files and in `mkdocs.yaml`. Type spaces instead.
......@@ -175,8 +227,8 @@ there is a list of conventions w.r.t. spelling and technical wording.
## Code Blocks and Command Prompts
Showing commands and sample output is an important part of all technical documentation. To make
things as clear for readers as possible and provide a consistent documentation, some guide lines have to
be followed.
things as clear as possible for readers and provide a consistent documentation, some guide lines
have to be followed.
1. Use ticks to mark code blocks and commands, not italic font.
1. Specify language for code blocks ([see below](#code-blocks-and-syntax-highlighting)).
......@@ -187,13 +239,18 @@ be followed.
### Long Options
We use long over short parameter names where possible to ease understanding.
The general guide line is to provide long over short parameter names where possible to ease
understanding. This holds especially for Slurm options, but also for other commands, e.g.,
use the `module` command over the short front-end `ml`.
??? example
!!! example
`srun --nodes=2 --ntasks-per-node=4 [...]`
`srun --nodes=2 --ntasks-per-node=4 ...` is preferred over `srun -N 2 -n 4 ...`
is preferred over
`srun -N 2 -n 4 [...]`
Use `module` over the short front-end `ml` in documentation and examples.
### Prompts
......@@ -202,6 +259,7 @@ This should help to avoid errors.
| Host/Partition | Prompt |
|------------------------|------------------|
| Localhost | `marie@local$` |
| Login nodes | `marie@login$` |
| Arbitrary compute node | `marie@compute$` |
| `haswell` partition | `marie@haswell$` |
......@@ -210,11 +268,10 @@ This should help to avoid errors.
| `romeo` partition | `marie@romeo$` |
| `julia` partition | `marie@julia$` |
| `dcv` partition | `marie@dcv$` |
| Localhost | `marie@local$` |
* **Always use a prompt**, even there is no output provided for the shown command.
* All code blocks which specify some general command templates, e.g. containing `<` and `>`
(see [Placeholders](#mark-placeholders)), should use `bash` for the code block. Additionally,
(see [unix rules](#unix-rules)), should use `bash` for the code block. Additionally,
an example invocation, perhaps with output, should be given with the normal `console` code block.
See also [Code Block description below](#code-blocks-and-syntax-highlighting).
* Using some magic, the prompt as well as the output is identified and will not be copied!
......@@ -222,108 +279,104 @@ This should help to avoid errors.
### Code Blocks and Syntax Highlighting
This project makes use of the extension
Providing code blocks and snippets is the meat and bones of this documentation.
Code blocks and command examples should give the general idea of invocation and be be as precise as
possible, i.e., allowing for copy-and-paste. Please mark replaceable code parts and optional and
required arguments as outlined in the section [required and optional arguments](#unix-rules) below.
Long, non-meaningful output should be ommitted.
We make use of the extension
[pymdownx.highlight](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/) for syntax
highlighting. There is a complete list of supported
highlighting. There is a complete list of supported
[language short codes](https://pygments.org/docs/lexers/).
For consistency, use the following short codes within this project:
???+ note "Syntax for commandline"
With the exception of command templates, use `console` for shell session and console:
For normal commands executed in the terminal, use the language short code `console`.
````markdown
```console
marie@login$ ls
foo
bar
```
````
````markdown
```console
marie@login$ module list
[...]
```
````
Make sure that shell session and console code blocks are executable on the login nodes of HPC system.
???+ note "Syntax for job files and scripts"
Command templates use [Placeholders](#mark-placeholders) to mark replaceable code parts. Command
templates should give a general idea of invocation and thus, do not contain any output. Use a
`bash` code block followed by an invocation example (with `console`):
Use the language short code `bash` for job files and shell scripts.
````markdown
```bash
marie@local$ ssh -NL <local port>:<compute node>:<remote port> taurus
```
````markdown
```bash
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --time=01:00:00
#SBATCH --output=slurm-%j.out
```console
marie@local$ ssh -NL 5901:172.24.146.46:5901 taurus
```
````
module load foss
Also use `bash` for shell scripts such as job files:
srun a.out
```
````
````markdown
```bash
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --time=01:00:00
#SBATCH --output=slurm-%j.out
??? note "Syntax for Python"
module load foss
`python` for Python source code:
srun a.out
```
````
`python` for Python source code:
````markdown
```python
from time import gmtime, strftime
print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
```
````
````markdown
```python
from time import gmtime, strftime
print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
```
````
And `pycon` for Python console:
`pycon` for Python console:
````markdown
```pycon
>>> from time import gmtime, strftime
>>> print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
2021-08-03 07:20:33
```
````
````markdown
```pycon
>>> from time import gmtime, strftime
>>> print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
2021-08-03 07:20:33
```
````
??? note "Line numbers"
Line numbers can be added via
More sugar can be applied by adding line numbers.
````markdown
```bash linenums="1"
#!/bin/bash
````markdown
```bash linenums="1"
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks=23
#SBATCH --time=02:10:00
#SBATCH --nodes=1
#SBATCH --ntasks=23
#SBATCH --time=02:10:00
srun a.out
```
````
srun a.out
```
````
_Result_:
_Result_:
![lines](misc/lines.png)
![lines](misc/lines.png)
Specific Lines can be highlighted by using
Specific Lines can be highlighted by using
```` markdown
```bash hl_lines="2 3"
#!/bin/bash
```` markdown
```bash hl_lines="2 3"
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks=23
#SBATCH --time=02:10:00
#SBATCH --nodes=1
#SBATCH --ntasks=23
#SBATCH --time=02:10:00
srun a.out
```
````
srun a.out
```
````
_Result_:
_Result_:
![lines](misc/highlight_lines.png)
![lines](misc/highlight_lines.png)
### Data Privacy and Generic Names
......@@ -349,24 +402,3 @@ Stick to the Unix rules on optional and required arguments, and selection of ite
* `<required argument or value>`
* `[optional argument or value]`
* `{choice1|choice2|choice3}`
## Random Things
**Remark:** Avoid using tabs both in markdown files and in `mkdocs.yaml`. Type spaces instead.
All graphics and attachments are saved within `misc` directory of the respective sub directory in
`docs`.
The syntax to insert a graphic or attachment into a page is
```Bash
![PuTTY: Switch on X11](misc/putty2.jpg)
{: align="center"}
```
The attribute `align` is optional. By default, graphics are left aligned. **Note:** It is crucial to
have `{: align="center"}` on a new line.
It is possible to add captions for tables and figures using `{: summary="This is a table caption"}`.
The `summary` and `align` parameters can be combined as well:
`{: summary="This is a table caption" align="top"}`.
doc.zih.tu-dresden.de/docs/contrib/contribute_browser.md
+ 1
− 1
View file @ af61a6f0
......@@ -97,7 +97,7 @@ into the `preview` branch of the repository.
As stated earlier, all changes undergo a review process.
This covers automated checks contained in the CI/CD pipeline and the review by a maintainer.
This is to ensure the quality of all contributions, e. g. by checking our
[content rules](content_rules.md).
[content rules](content_guide_lines.md).
You can follow this process under
[Merge requests](https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium/-/merge_requests)
(where you initiated your merge request).
......
doc.zih.tu-dresden.de/docs/contrib/contribute_container.md
+ 3
− 3
View file @ af61a6f0
......@@ -47,7 +47,7 @@ can [run checks locally](#run-the-proposed-checks-inside-container).
!!! tip
When you contribute, please follow our [content rules](content_rules.md) to make incorporating
When you contribute, please follow our [content rules](content_guide_lines.md) to make incorporating
your changes easy. We also check these rules via continuous integration checks and/or reviews.
You can find the details and commands to [preview your changes](#start-the-local-web-server) and
[apply checks](#run-the-proposed-checks-inside-container).
......@@ -70,7 +70,7 @@ problems, such as changes in the Dockerfile or any script could.
1. The developer needs to fix things that were found by CI.
1. The developer informs you about the MR or asks for your support while fixing the CI.
When you follow our [content rules](content_rules.md) and
When you follow our [content rules](content_guide_lines.md) and
[run checks locally](#run-the-proposed-checks-inside-container), you are making this process
faster.
......@@ -137,7 +137,7 @@ In our continuous integration (CI) pipeline, a merge request triggers the automa
* correct text format.
These checks ensure a high quality and consistency of the content and follow our
[content rules](content_rules.md). If one of them fails, the merge request will not be accepted. To
[content rules](content_guide_lines.md). If one of them fails, the merge request will not be accepted. To
prevent this, you can run these checks locally and adapt your files accordingly.
You are now ready to use the different checks, however we suggest to try the pre-commit hook.
......
doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
+ 8
− 15
View file @ af61a6f0
......@@ -5,26 +5,19 @@
Ink is better than the best memory.
This documentation is written in markdown and translated into static html pages using
[mkdocs](https://www.mkdocs.org/). There is a single configuration file holding the pages structure
[mkdocs](https://www.mkdocs.org/). A single configuration file holds the pages structure
as well as specification of the theme and extensions. This file is `mkdocs.yaml`.
All essential files (markdown pages, graphics, configuration, theme, etc.) are managed within a git
All essential files (markdown pages, graphics, configuration, theme, etc.) are managed within a Git
repository which makes it quite easy to contribute to this documentation. In principle, there are
three possible ways how to contribute to this documentation. These ways are outlined below.
Please refer to the [content guide lines page](content_guide_lines.md) regarding markdown syntax
and writing style.
Even though we try to cover all aspects of working with the ZIH systems and keep the documentation
up to date, you might miss something. In principle, there are three possible ways how you can
contribute to this documentation as outlined below.
## Content Rules
## Content Guide Lines
To ensure a high-quality and consistent documentation and to make it easier for readers to
understand all content, we set some [content rules](content_rules.md). Please follow these rules
when contributing! Furthermore, reviewing your changes take less time and your improvements appear
faster on the official documentation.
understand all content, we set some [content guide lines](content_guide_lines.md). Please follow
these rules regarding markdown syntax and writing style when contributing! Furthermore, reviewing
your changes take less time and your improvements appear faster on the official documentation.
!!! note
......@@ -54,7 +47,7 @@ documentation.
If you have a web browser (most probably you are using it to read this page) and want to contribute
to the documentation, you are good to go. GitLab offers a rich and versatile web interface to work
with repositories. To start fixing typos and edit source files, please find more information on
[Contributing via web browser](contribute_browser.md).
the page [Contributing via web browser](contribute_browser.md).
## Contribute via Local Clone
......@@ -62,4 +55,4 @@ For experienced Git users, we provide a Docker container that includes all check
used in the back-end. Using them should ensure that merge requests will not be blocked
due to automatic checking.
The page on [Contributing via local clone](contribute_container.md) provides you with the details
about how to setup and use your local clone.
about how to setup and use your local clone of the repository.
doc.zih.tu-dresden.de/mkdocs.yml
+ 1
− 1
View file @ af61a6f0
......@@ -128,7 +128,7 @@ nav:
- Windows Batchjobs: archive/windows_batch.md
- Contribute:
- How-To Contribute: contrib/howto_contribute.md
- Content Rules: contrib/content_rules.md
- Content Guide Lines: contrib/content_guide_lines.md
- Contribute via Browser: contrib/contribute_browser.md
- Contribute via Local Clone: contrib/contribute_container.md
......
doc.zih.tu-dresden.de/util/grep-forbidden-patterns.sh
+ 9
− 9
View file @ af61a6f0
......@@ -14,22 +14,22 @@ basedir=`dirname "$basedir"`
#For example, the first rule says:
# The pattern \<io\> should not be present in any file (case-insensitive match), except when it appears as ".io".
ruleset="The word \"IO\" should not be used, use \"I/O\" instead.
doc.zih.tu-dresden.de/docs/contrib/content_rules.md
doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
i \<io\> \.io
\"SLURM\" (only capital letters) should not be used, use \"Slurm\" instead.
doc.zih.tu-dresden.de/docs/contrib/content_rules.md
doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
s \<SLURM\>
\"File system\" should be written as \"filesystem\", except when used as part of a proper name.
doc.zih.tu-dresden.de/docs/contrib/content_rules.md
doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
i file \+system HDFS
Use \"ZIH systems\" or \"ZIH system\" instead of \"Taurus\". \"taurus\" is only allowed when used in ssh commands and other very specific situations.
doc.zih.tu-dresden.de/docs/contrib/content_rules.md doc.zih.tu-dresden.de/docs/archive/phase2_migration.md
doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md doc.zih.tu-dresden.de/docs/archive/phase2_migration.md
i \<taurus\> taurus\.hrsk /taurus /TAURUS ssh ^[0-9]\+:Host taurus$
\"HRSKII\" should be avoided, use \"ZIH system\" instead.
doc.zih.tu-dresden.de/docs/contrib/content_rules.md
doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
i \<hrskii\>
The term \"HPC-DA\" should be avoided. Depending on the situation, use \"data analytics\" or similar.
doc.zih.tu-dresden.de/docs/contrib/content_rules.md
doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
i hpc[ -]\+da\>
\"ATTACHURL\" was a keyword in the old wiki, don't use it.
......@@ -56,13 +56,13 @@ Internal links should not contain \"/#\".
i (.*/#.*) (http
When referencing partitions, put keyword \"partition\" in front of partition name, e. g. \"partition ml\", not \"ml partition\".
doc.zih.tu-dresden.de/docs/contrib/content_rules.md
doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
i \(alpha\|ml\|haswell\|romeo\|gpu\|smp\|julia\|hpdlf\|scs5\|dcv\)-\?\(interactive\)\?[^a-z|]*partition
Give hints in the link text. Words such as \"here\" or \"this link\" are meaningless.
doc.zih.tu-dresden.de/docs/contrib/content_rules.md
doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
i \[\s\?\(documentation\|here\|more info\|\(this \)\?\(link\|page\|subsection\)\|slides\?\|manpage\)\s\?\]
Use \"workspace\" instead of \"work space\" or \"work-space\".
doc.zih.tu-dresden.de/docs/contrib/content_rules.md
doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
i work[ -]\+space"
function grepExceptions () {
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
Nutzungsbedingungen | Datenschutzerklärung | Barrierefreiheitserklärung