Skip to content

CPLYTM-876 - Include documentation and hints for YAML linting #13606

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jan-cerny merged 2 commits into from
Jun 20, 2025
Merged

CPLYTM-876 - Include documentation and hints for YAML linting #13606

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8945cb3
Include documentation and hints for YAML linting
marcusburghardt Jun 19, 2025
0ff044e
Fix typo and improve summary in <details>
marcusburghardt Jun 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/manual/developer/04_style_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,26 @@ and keep these guidelines in mind when writing new code.
* Shall use the `.yml` vs `.yaml` for the file extension
* Shall have one blank line between sections

<details>
Copy link
Collaborator

@jan-cerny jan-cerny Jun 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick: I would refrain from using the <details>, I feel that it makes the content quite hidden or less visible.

Copy link
Member Author

@marcusburghardt marcusburghardt Jun 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My intention was to not create noise in the Style Guide style, which is expected to be the first documentation a contributor will check once hitting the CI Lint test. I also considered to move this somewhere else, but it is a small content and a reference in Style Guide would still be necessary. Maybe we can make the summary more intuitive. For example: Hint: Linting Tools to check and fix lint issues. WDYT?

Copy link
Member Author

@marcusburghardt marcusburghardt Jun 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I included the suggestion in the last commit. It would looks like this:
Hint for linting tools

Copy link
Collaborator

@jan-cerny jan-cerny Jun 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, thanks!

<summary>Hint: Linting Tools to Check and Fix Lint Issues</summary><br/>
You can test and fix lint issues locally using two python tools:

```bash
pip install yamllint yamlfix
```

Use `yamllint` to check the files
```bash
yamllint -c .yamllint <file>
```

Use `yamlfix` to automatically fix lint issues
```bash
yamlfix -c yamlfix.toml <file>
Copy link
Collaborator

@jan-cerny jan-cerny Jun 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have tried it on multiple control files and it works great.

```
These configuration files are available in the root directory of the repository.
</details>

#### HTML Like Fields

The sections below that are marked with `(HTML Like)` means that a limited number of HTML elements are supported in these sections.
Expand Down
17 changes: 17 additions & 0 deletions yamlfix.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Indentation settings
indent_mapping = 4
indent_offset = 4
indent_sequence = 6

# Quote settings
preserve_quotes = "True"
quote_basic_values = "False"
quote_keys_and_basic_values = "False"

# Line settings
line_length = 99
whitelines = 1
section_whitelines = 1

# Other settings
sequence_style = "block_style"
Loading