Examples in the documentation has yamllint errors!

[lindhe]

Maybe it's just me, but I find it unacceptable that the examples on https://yamllint.readthedocs.io/ has yamllint errors in them! 🤣

At the very least, the examples for extending configurations do not adhere to the document-start rule.

This should obviously be fixed! :)

The easy way is to just look through the docs and try to fix things. But that's very fragile. The good way is to implement some sort of templating system that includes content from YAML files, and then we can run yamllint in CI on those files very easily.

[adrienverge]

Hello Andreas,

If I understand correctly, you're referring to the lack of --- in snippets of the documentation on how to extend configuration. This is not an error, the YAML spec allows it. Tokens --- are optional, and reported by yamllint only if the yamllint users enabled the document-start rule (or chose a default conf that enables it).

Examples shown in the documentation are meant to be short and easily understandable.

[lindhe]

Yes, that's it. :)

(or chose a default conf that enables it)

Apparently I'm not thinking of the default conf in the right way then. I thought it was supposed to be included basically always. Whats the default if default is not included?

[adrienverge]

I understand that it's not super-clear for newcomers :wink: In short: yamllint always needs a configuration file to tell it what to do (e.g. 2-space indentation or 4-space indentation? allow octal values or not?) For users that omit such a configuration, yamllint uses this one, but keep in mind that this set of rules is very subjective. Everyone is advised to use their own configuration.

About your initial concern: I'd rather not adding --- to these documentation examples, in order to keep things simple and clear. Is it OK for you?

[lindhe]

That's OK.