diff --git a/yamllint/rules/braces.py b/yamllint/rules/braces.py index 2aa2e1d..78464c3 100644 --- a/yamllint/rules/braces.py +++ b/yamllint/rules/braces.py @@ -14,6 +14,54 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to control the number of spaces inside braces (``{`` and ``}``). + +.. rubric:: Options + +* ``min-spaces-inside`` defines the minimal number of spaces required inside + braces. +* ``max-spaces-inside`` defines the maximal number of spaces allowed inside + braces. + +.. rubric:: Examples + +#. With ``braces: {min-spaces-inside: 0, max-spaces-inside: 0}`` + + the following code snippet would **PASS**: + :: + + object: {key1: 4, key2: 8} + + the following code snippet would **FAIL**: + :: + + object: { key1: 4, key2: 8 } + +#. With ``braces: {min-spaces-inside: 1, max-spaces-inside: 3}`` + + the following code snippet would **PASS**: + :: + + object: { key1: 4, key2: 8 } + + the following code snippet would **PASS**: + :: + + object: { key1: 4, key2: 8 } + + the following code snippet would **FAIL**: + :: + + object: { key1: 4, key2: 8 } + + the following code snippet would **FAIL**: + :: + + object: {key1: 4, key2: 8 } +""" + + import yaml from yamllint.rules.common import spaces_after, spaces_before diff --git a/yamllint/rules/brackets.py b/yamllint/rules/brackets.py index e27a3bc..b2a94e3 100644 --- a/yamllint/rules/brackets.py +++ b/yamllint/rules/brackets.py @@ -14,6 +14,55 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to control the number of spaces inside brackets (``[`` and +``]``). + +.. rubric:: Options + +* ``min-spaces-inside`` defines the minimal number of spaces required inside + brackets. +* ``max-spaces-inside`` defines the maximal number of spaces allowed inside + brackets. + +.. rubric:: Examples + +#. With ``brackets: {min-spaces-inside: 0, max-spaces-inside: 0}`` + + the following code snippet would **PASS**: + :: + + object: [1, 2, abc] + + the following code snippet would **FAIL**: + :: + + object: [ 1, 2, abc ] + +#. With ``brackets: {min-spaces-inside: 1, max-spaces-inside: 3}`` + + the following code snippet would **PASS**: + :: + + object: [ 1, 2, abc ] + + the following code snippet would **PASS**: + :: + + object: [ 1, 2, abc ] + + the following code snippet would **FAIL**: + :: + + object: [ 1, 2, abc ] + + the following code snippet would **FAIL**: + :: + + object: [1, 2, abc ] +""" + + import yaml from yamllint.rules.common import spaces_after, spaces_before diff --git a/yamllint/rules/colons.py b/yamllint/rules/colons.py index 6868147..9bfdd14 100644 --- a/yamllint/rules/colons.py +++ b/yamllint/rules/colons.py @@ -14,6 +14,62 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to control the number of spaces before and after colons (``:``). + +.. rubric:: Options + +* ``max-spaces-before`` defines the maximal number of spaces allowed before + colons (use ``-1`` to disable). +* ``max-spaces-after`` defines the maximal number of spaces allowed after + colons (use ``-1`` to disable). + +.. rubric:: Examples + +#. With ``colons: {max-spaces-before: 0, max-spaces-after: 1}`` + + the following code snippet would **PASS**: + :: + + object: + - a + - b + key: value + +#. With ``colons: {max-spaces-before: 1}`` + + the following code snippet would **PASS**: + :: + + object : + - a + - b + + the following code snippet would **FAIL**: + :: + + object : + - a + - b + +#. With ``colons: {max-spaces-after: 2}`` + + the following code snippet would **PASS**: + :: + + first: 1 + second: 2 + third: 3 + + the following code snippet would **FAIL**: + :: + + first: 1 + 2nd: 2 + third: 3 +""" + + import yaml from yamllint.rules.common import spaces_after, spaces_before, is_explicit_key diff --git a/yamllint/rules/commas.py b/yamllint/rules/commas.py index 3ef3b99..3fbd932 100644 --- a/yamllint/rules/commas.py +++ b/yamllint/rules/commas.py @@ -14,6 +14,54 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to control the number of spaces before and after commas (``,``). + +.. rubric:: Options + +* ``max-spaces-before`` defines the maximal number of spaces allowed before + commas (use ``-1`` to disable). +* ``max-spaces-after`` defines the maximal number of spaces allowed after + commas (use ``-1`` to disable). + +.. rubric:: Examples + +#. With ``commas: {max-spaces-before: 0, max-spaces-after: 1}`` + + the following code snippet would **PASS**: + :: + + strange var: + [10, 20, 30, {x: 1, y: 2}] + + the following code snippet would **FAIL**: + :: + + strange var: + [10, 20 , 30, {x: 1, y: 2}] + + the following code snippet would **FAIL**: + :: + + strange var: + [10, 20, 30, {x: 1, y: 2}] + +#. With ``commas: {max-spaces-before: 2, max-spaces-after: 2}`` + + the following code snippet would **PASS**: + :: + + strange var: + [10 , 20 , 30, {x: 1 , y: 2}] + + the following code snippet would **FAIL**: + :: + + strange var: + [10 , 20 , 30, {x: 1 , y: 2}] +""" + + import yaml from yamllint.errors import LintProblem diff --git a/yamllint/rules/comments.py b/yamllint/rules/comments.py index 854755e..4ad224a 100644 --- a/yamllint/rules/comments.py +++ b/yamllint/rules/comments.py @@ -14,6 +14,47 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to control the position and formatting of comments. + +.. rubric:: Options + +* Use ``require-starting-space`` to require a space character right after the + ``#``. Set to ``yes`` to enable, ``no`` to disable. +* ``min-spaces-from-content`` is used to visually separate inline comments from + content. It defines the minimal required number of spaces between a comment + and its preceding content. + +.. rubric:: Examples + +#. With ``comments: {require-starting-space: yes}`` + + the following code snippet would **PASS**: + :: + + # This sentence + # is a block comment + + the following code snippet would **FAIL**: + :: + + #This sentence + #is a block comment + +#. With ``comments: {min-spaces-from-content: 2}`` + + the following code snippet would **PASS**: + :: + + x = 2 ^ 127 - 1 # Mersenne prime number + + the following code snippet would **FAIL**: + :: + + x = 2 ^ 127 - 1 # Mersenne prime number +""" + + import yaml from yamllint.errors import LintProblem diff --git a/yamllint/rules/comments_indentation.py b/yamllint/rules/comments_indentation.py index 3a44252..6fa80eb 100644 --- a/yamllint/rules/comments_indentation.py +++ b/yamllint/rules/comments_indentation.py @@ -14,6 +14,67 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to force comments to be indented like content. + +.. rubric:: Examples + +#. With ``comments-indentation: {}`` + + the following code snippet would **PASS**: + :: + + # Fibonacci + [0, 1, 1, 2, 3, 5] + + the following code snippet would **FAIL**: + :: + + # Fibonacci + [0, 1, 1, 2, 3, 5] + + the following code snippet would **PASS**: + :: + + list: + - 2 + - 3 + # - 4 + - 5 + + the following code snippet would **FAIL**: + :: + + list: + - 2 + - 3 + # - 4 + - 5 + + the following code snippet would **PASS**: + :: + + # This is the first object + obj1: + - item A + # - item B + # This is the second object + obj2: [] + + the following code snippet would **PASS**: + :: + + # This sentence + # is a block comment + + the following code snippet would **FAIL**: + :: + + # This sentence + # is a block comment +""" + + import yaml from yamllint.errors import LintProblem diff --git a/yamllint/rules/document_end.py b/yamllint/rules/document_end.py index 0336eb7..14417c4 100644 --- a/yamllint/rules/document_end.py +++ b/yamllint/rules/document_end.py @@ -14,6 +14,66 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to require or forbid the use of document end marker (``...``). + +.. rubric:: Options + +* Set ``present`` to ``yes`` when the document end marker is required, or to + ``no`` when it is forbidden. + +.. rubric:: Examples + +#. With ``document-end: {present: yes}`` + + the following code snippet would **PASS**: + :: + + --- + this: + is: [a, document] + ... + --- + - this + - is: another one + ... + + the following code snippet would **FAIL**: + :: + + --- + this: + is: [a, document] + --- + - this + - is: another one + ... + +#. With ``document-end: {present: no}`` + + the following code snippet would **PASS**: + :: + + --- + this: + is: [a, document] + --- + - this + - is: another one + + the following code snippet would **FAIL**: + :: + + --- + this: + is: [a, document] + ... + --- + - this + - is: another one +""" + + import yaml from yamllint.errors import LintProblem diff --git a/yamllint/rules/document_start.py b/yamllint/rules/document_start.py index 476488f..7e3ff73 100644 --- a/yamllint/rules/document_start.py +++ b/yamllint/rules/document_start.py @@ -14,6 +14,56 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to require or forbid the use of document start marker (``---``). + +.. rubric:: Options + +* Set ``present`` to ``yes`` when the document start marker is required, or to + ``no`` when it is forbidden. + +.. rubric:: Examples + +#. With ``document-start: {present: yes}`` + + the following code snippet would **PASS**: + :: + + --- + this: + is: [a, document] + --- + - this + - is: another one + + the following code snippet would **FAIL**: + :: + + this: + is: [a, document] + --- + - this + - is: another one + +#. With ``document-start: {present: no}`` + + the following code snippet would **PASS**: + :: + + this: + is: [a, document] + ... + + the following code snippet would **FAIL**: + :: + + --- + this: + is: [a, document] + ... +""" + + import yaml from yamllint.errors import LintProblem diff --git a/yamllint/rules/empty_lines.py b/yamllint/rules/empty_lines.py index 3023796..b8a9158 100644 --- a/yamllint/rules/empty_lines.py +++ b/yamllint/rules/empty_lines.py @@ -14,6 +14,42 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to set a maximal number of allowed consecutive blank lines. + +.. rubric:: Options + +* ``max`` defines the maximal number of empty lines allowed in the document. +* ``max-start`` defines the maximal number of empty lines allowed at the + beginning of the file. This option takes precedence over ``max``. +* ``max-end`` defines the maximal number of empty lines allowed at the end of + the file. This option takes precedence over ``max``. + +.. rubric:: Examples + +#. With ``empty-lines: {max: 1}`` + + the following code snippet would **PASS**: + :: + + - foo: + - 1 + - 2 + + - bar: [3, 4] + + the following code snippet would **FAIL**: + :: + + - foo: + - 1 + - 2 + + + - bar: [3, 4] +""" + + from yamllint.errors import LintProblem diff --git a/yamllint/rules/hyphens.py b/yamllint/rules/hyphens.py index 1702c50..1d3702d 100644 --- a/yamllint/rules/hyphens.py +++ b/yamllint/rules/hyphens.py @@ -14,6 +14,60 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to control the number of spaces after hyphens (``-``). + +.. rubric:: Options + +* ``max-spaces-after`` defines the maximal number of spaces allowed after + hyphens. + +.. rubric:: Examples + +#. With ``hyphens: {max-spaces-after: 1}`` + + the following code snippet would **PASS**: + :: + + - first list: + - a + - b + - - 1 + - 2 + - 3 + + the following code snippet would **FAIL**: + :: + + - first list: + - a + - b + + the following code snippet would **FAIL**: + :: + + - - 1 + - 2 + - 3 + +#. With ``hyphens: {max-spaces-after: 3}`` + + the following code snippet would **PASS**: + :: + + - key + - key2 + - key42 + + the following code snippet would **FAIL**: + :: + + - key + - key2 + - key42 +""" + + import yaml from yamllint.rules.common import spaces_after diff --git a/yamllint/rules/indentation.py b/yamllint/rules/indentation.py index 224485d..3edae82 100644 --- a/yamllint/rules/indentation.py +++ b/yamllint/rules/indentation.py @@ -14,6 +14,122 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to control the indentation. + +.. rubric:: Options + +* ``spaces`` defines the number of spaces that represent an indentation level. +* ``indent-sequences`` defines whether block sequences should be indented or + not (when in a mapping, this indentation is not mandatory -- some people + perceive the ``-`` as part of the indentation). Possible values: ``yes``, + ``no`` and ``whatever`` (the latter means either indenting or not indenting + block sequences is OK. +* ``check-multi-line-strings`` defines whether to lint indentation in + multi-line strings. Set to ``yes`` to enable, ``no`` to disable. + +.. rubric:: Examples + +#. With ``indentation: {spaces: 1}`` + + the following code snippet would **PASS**: + :: + + history: + - name: Unix + date: 1969 + - name: Linux + date: 1991 + nest: + recurse: + - haystack: + needle + +#. With ``indentation: {spaces: 4}`` + + the following code snippet would **PASS**: + :: + + history: + - name: Unix + date: 1969 + - name: Linux + date: 1991 + nest: + recurse: + - haystack: + needle + + the following code snippet would **FAIL**: + :: + + history: + - name: Unix + date: 1969 + - name: Linux + date: 1991 + nest: + recurse: + - haystack: + needle + +#. With ``indentation: {spaces: 2, indent-sequences: no}`` + + the following code snippet would **PASS**: + :: + + list: + - flying + - spaghetti + - monster + + the following code snippet would **FAIL**: + :: + + list: + - flying + - spaghetti + - monster + +#. With ``indentation: {spaces: 2, indent-sequences: whatever}`` + + the following code snippet would **PASS**: + :: + + list: + - flying: + - spaghetti + - monster + - not flying: + - spaghetti + - sauce + +#. With ``indentation: {spaces: 4, check-multi-line-strings: yes}`` + + the following code snippet would **PASS**: + :: + + Blaise Pascal: + Je vous écris une longue lettre parce que + je n'ai pas le temps d'en écrire une courte. + + the following code snippet would **FAIL**: + :: + + C code: + void main() { + printf("foo"); + } + + the following code snippet would **PASS**: + :: + + C code: + void main() { + printf("bar"); + } +""" + import yaml from yamllint.errors import LintProblem diff --git a/yamllint/rules/line_length.py b/yamllint/rules/line_length.py index 23186dc..5abb7ba 100644 --- a/yamllint/rules/line_length.py +++ b/yamllint/rules/line_length.py @@ -14,6 +14,33 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to set a limit to lines length. + +.. rubric:: Options + +* ``max`` defines the maximal (inclusive) length of lines. + +.. rubric:: Examples + +#. With ``line-length: {max: 70}`` + + the following code snippet would **PASS**: + :: + + long sentence: + Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do + eiusmod tempor incididunt ut labore et dolore magna aliqua. + + the following code snippet would **FAIL**: + :: + + long sentence: + Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod + tempor incididunt ut labore et dolore magna aliqua. +""" + + from yamllint.errors import LintProblem diff --git a/yamllint/rules/new_line_at_end_of_file.py b/yamllint/rules/new_line_at_end_of_file.py index 56b0ed6..f577098 100644 --- a/yamllint/rules/new_line_at_end_of_file.py +++ b/yamllint/rules/new_line_at_end_of_file.py @@ -14,6 +14,16 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to require a new line character (``\\n``) at the end of files. + +The POSIX standard `requires the last line to end with a new line character +`_. +All UNIX tools expect a new line at the end of files. Most text editors use +this convention too. +""" + + from yamllint.errors import LintProblem diff --git a/yamllint/rules/new_lines.py b/yamllint/rules/new_lines.py index 5b95e37..d085c9c 100644 --- a/yamllint/rules/new_lines.py +++ b/yamllint/rules/new_lines.py @@ -14,6 +14,16 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to force the type of new line characters. + +.. rubric:: Options + +* Set ``type`` to ``unix`` to use UNIX-typed new line characters (``\\n``), or + ``dos`` to use DOS-typed new line characters (``\\r\\n``). +""" + + from yamllint.errors import LintProblem diff --git a/yamllint/rules/trailing_spaces.py b/yamllint/rules/trailing_spaces.py index a463049..ec215f8 100644 --- a/yamllint/rules/trailing_spaces.py +++ b/yamllint/rules/trailing_spaces.py @@ -14,6 +14,29 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +""" +Use this rule to forbid trailing spaces at the end of lines. + +.. rubric:: Examples + +#. With ``trailing-spaces: {}`` + + the following code snippet would **PASS**: + :: + + this document doesn't contain + any trailing + spaces + + the following code snippet would **FAIL**: + :: + + this document contains """ """ + trailing spaces + on lines 1 and 3 """ """ +""" + + import string from yamllint.errors import LintProblem