From 04e84ffcb4afa3fc89df2dc6fdf9c1d2003603fe Mon Sep 17 00:00:00 2001 From: Ulf Markwardt <ulf.markwardt@tu-dresden.de> Date: Mon, 27 Sep 2021 08:39:09 +0200 Subject: [PATCH] Contrib wieder aus dem wiki genommen --- .../content_rules.md => content_rules.md | 0 contribute_container.md | 67 ++++++--- .../docs/contrib/contribute_container.md | 133 ------------------ ...howto_contribute.md => howto_contribute.md | 0 4 files changed, 46 insertions(+), 154 deletions(-) rename doc.zih.tu-dresden.de/docs/contrib/content_rules.md => content_rules.md (100%) delete mode 100644 doc.zih.tu-dresden.de/docs/contrib/contribute_container.md rename doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md => howto_contribute.md (100%) diff --git a/doc.zih.tu-dresden.de/docs/contrib/content_rules.md b/content_rules.md similarity index 100% rename from doc.zih.tu-dresden.de/docs/contrib/content_rules.md rename to content_rules.md diff --git a/contribute_container.md b/contribute_container.md index 6f6d74389..d050940d2 100644 --- a/contribute_container.md +++ b/contribute_container.md @@ -1,26 +1,40 @@ # Contributing Using a Local Clone and a Docker Container -see also: [https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium/-/blob/preview/doc.zih.tu-dresden.de/README.md] +## Git Procedure + +Please follow this standard Git procedure for working with a local clone: + +1. Change to a local (unencrypted) filesystem. (We have seen problems running the container +an ecryptfs filesystem. So you might +want to use e.g. `/tmp` as root directory.) +1. Get a clone of the Git repository: `git clone git@gitlab.hrz.tu-chemnitz.de:zih/hpc-compendium/hpc-compendium.git` +1. Change to the root of the local clone: `cd hpc-compendium` +1. Create a new feature branch for you to work in. Ideally name it like the file you want +to modify. `git checkout -b <BRANCHNAME>`. (Navigation section can be found in `mkdocs.yaml`.) +1. Add/correct the documentation with your preferred editor. +1. Run the correctness checks until everything is fine. - Incorrect files will be rejected +automatically by our CI pipeline. +1. Commit the changes with `git commit -m "<DESCRIPTION>" <FILE LIST>`. Include a description +of the change and a list of all changed files. +1. Push the local changes to the global feature branch with `git push origin <BRANCHNAME>`. +1. As an output you get a link to create a merge request against the preview branch. + +You can find the details and command in the next section. -## Prerequisites +## Preparation -Assuming you understand in principle how to work with our git. Now you need: +Assuming you understand in principle how to work with our Git. Now you need: * a system with running Docker installation * all necessary access/execution rights * a local clone of the repository in the directory `./hpc-compendium` -Remark: We have seen problems running the container an ecryptfs filesystem. So you might -want to use `/tmp` as root directory. - -## Preparation - Build the docker image. This might take a bit longer, but you have to -run it only once in a while (when we have changed the Dockerfile). +run it only once in a while. ```Bash cd hpc-compendium -docker build -t hpc-compendium . +docker build -t hpc-compendium . ``` ## Working with the Docker Container @@ -53,7 +67,18 @@ the merge. ### Run the Proposed Checks Inside Container -Remember to keep the local web server running in the other shell. +In our continuous integration (CI) pipeline, a merge request triggers the automated check of + +* correct links, +* correct spelling, +* correct text format. + +If one of them fails the merge request will be rejected. To prevent this you can run these +checks locally and adapt your files accordingly. + +!!! note + + Remember to keep the local web server running in the other shell. First, change to the `hpc-compendium` directory and set the environment variable DC to save a lot of keystrokes :-) @@ -64,15 +89,6 @@ export DC='docker exec -it hpc-compendium bash -c ' and use it like this... -#### Linter - -If you want to check whether the markdown files are formatted -properly, use the following command: - -```Bash -$DC 'markdownlint docs' -``` - #### Link Checker To check a single file, e.g. @@ -94,7 +110,8 @@ $DC 'find docs -type f -name "*.md" | xargs -L1 markdown-link-check' For spell-checking a single file, , e.g. `doc.zih.tu-dresden.de/docs/software/big_data_frameworks.md`, use: -```$DC './util/check-spelling.sh docs/software/big_data_frameworks.md' +```Bash +$DC './util/check-spelling.sh docs/software/big_data_frameworks.md' ``` For spell-checking all files, use: @@ -106,3 +123,11 @@ $DC ./util/check-spelling.sh This outputs all words of all files that are unknown to the spell checker. To let the spell checker "know" a word, append it to `doc.zih.tu-dresden.de/wordlist.aspell`. + +#### Linter + +If you want to check whether the markdown files are formatted properly, use the following command: + +```Bash +$DC 'markdownlint docs' +``` diff --git a/doc.zih.tu-dresden.de/docs/contrib/contribute_container.md b/doc.zih.tu-dresden.de/docs/contrib/contribute_container.md deleted file mode 100644 index d050940d2..000000000 --- a/doc.zih.tu-dresden.de/docs/contrib/contribute_container.md +++ /dev/null @@ -1,133 +0,0 @@ -# Contributing Using a Local Clone and a Docker Container - -## Git Procedure - -Please follow this standard Git procedure for working with a local clone: - -1. Change to a local (unencrypted) filesystem. (We have seen problems running the container -an ecryptfs filesystem. So you might -want to use e.g. `/tmp` as root directory.) -1. Get a clone of the Git repository: `git clone git@gitlab.hrz.tu-chemnitz.de:zih/hpc-compendium/hpc-compendium.git` -1. Change to the root of the local clone: `cd hpc-compendium` -1. Create a new feature branch for you to work in. Ideally name it like the file you want -to modify. `git checkout -b <BRANCHNAME>`. (Navigation section can be found in `mkdocs.yaml`.) -1. Add/correct the documentation with your preferred editor. -1. Run the correctness checks until everything is fine. - Incorrect files will be rejected -automatically by our CI pipeline. -1. Commit the changes with `git commit -m "<DESCRIPTION>" <FILE LIST>`. Include a description -of the change and a list of all changed files. -1. Push the local changes to the global feature branch with `git push origin <BRANCHNAME>`. -1. As an output you get a link to create a merge request against the preview branch. - -You can find the details and command in the next section. - -## Preparation - -Assuming you understand in principle how to work with our Git. Now you need: - -* a system with running Docker installation -* all necessary access/execution rights -* a local clone of the repository in the directory `./hpc-compendium` - -Build the docker image. This might take a bit longer, but you have to -run it only once in a while. - -```Bash -cd hpc-compendium -docker build -t hpc-compendium . -``` - -## Working with the Docker Container - -Here is a suggestion of a workflow which might be suitable for you. - -### Start the Local Web Server - -The command(s) to start the dockerized web server is this: - -```Bash -docker run --name=hpc-compendium -p 8000:8000 --rm -it -w /docs \ - -v /tmp/hpc-compendium/doc.zih.tu-dresden.de:/docs:z hpc-compendium bash \ - -c 'mkdocs build && mkdocs serve -a 0.0.0.0:8000' -``` - -To follow its progress let it run in a single shell (terminal window) -and open another one for the other steps. - -You can view the documentation via -[http://localhost:8000](http://localhost:8000) in your browser, now. - -You can now update the contents in you preferred editor. -The running container automatically takes care of file changes and rebuilds the -documentation. - -With the details described below, it will then be easy to follow the guidelines -for local correctness checks before submitting your changes and requesting -the merge. - -### Run the Proposed Checks Inside Container - -In our continuous integration (CI) pipeline, a merge request triggers the automated check of - -* correct links, -* correct spelling, -* correct text format. - -If one of them fails the merge request will be rejected. To prevent this you can run these -checks locally and adapt your files accordingly. - -!!! note - - Remember to keep the local web server running in the other shell. - -First, change to the `hpc-compendium` directory and set the environment -variable DC to save a lot of keystrokes :-) - -```Bash -export DC='docker exec -it hpc-compendium bash -c ' -``` - -and use it like this... - -#### Link Checker - -To check a single file, e.g. -`doc.zih.tu-dresden.de/docs/software/big_data_frameworks.md`, use: - -```Bash -$DC 'markdown-link-check docs/software/big_data_frameworks.md' -``` - -To check whether there are links that point to a wrong target, use -(this may take a while and gives a lot of output because it runs over all files): - -```Bash -$DC 'find docs -type f -name "*.md" | xargs -L1 markdown-link-check' -``` - -#### Spell Checker - -For spell-checking a single file, , e.g. -`doc.zih.tu-dresden.de/docs/software/big_data_frameworks.md`, use: - -```Bash -$DC './util/check-spelling.sh docs/software/big_data_frameworks.md' -``` - -For spell-checking all files, use: - -```Bash -$DC ./util/check-spelling.sh -``` - -This outputs all words of all files that are unknown to the spell checker. -To let the spell checker "know" a word, append it to -`doc.zih.tu-dresden.de/wordlist.aspell`. - -#### Linter - -If you want to check whether the markdown files are formatted properly, use the following command: - -```Bash -$DC 'markdownlint docs' -``` diff --git a/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md b/howto_contribute.md similarity index 100% rename from doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md rename to howto_contribute.md -- GitLab