Doc: Document rules

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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
 
 

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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

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 <http://www.gnu.org/licenses/>.
 
+"""
+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
 
 

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 <http://www.gnu.org/licenses/>.
 
+"""
+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
+<http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_206>`_.
+All UNIX tools expect a new line at the end of files. Most text editors use
+this convention too.
+"""
+
+
 from yamllint.errors import LintProblem
 
 

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 <http://www.gnu.org/licenses/>.
 
+"""
+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
 
 

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 <http://www.gnu.org/licenses/>.
 
+"""
+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