diff --git a/docs/development.rst b/docs/development.rst index a706836..3060b34 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -16,3 +16,47 @@ Basic example of running the linter from Python: .. automodule:: yamllint.linter :members: + +Develop rule plugins +--------------------- + +yamllint provides a plugin mechanism using setuptools (pkg_resources) to allow +adding custom rules. So, you can extend yamllint and add rules with your own +custom yamllint rule plugins if you developed them. + +Yamllint rule plugins must satisfy the followings. + +#. It must be a Python package installable using pip and distributed under + GPLv3+ same as yamllint. +#. It must contains the entry point configuration in ``setup.cfg`` or something + similar packaging configuration files, to make it installed and working as a + yamllint plugin like below. (```` is that plugin name and + ```` is a dir where the rule modules exist.) + :: + + [options.entry_points] + yamllint.plugins.rules = + = + +#. It must contain custom yamllint rule modules: + + - Each rule module must define a couple of global variables, ID and TYPE. ID + must not conflicts with other rules' ID. + - Each rule module must define a function named 'check' to test input data + complies with the rule. + - Each rule module may have other global variables. + + - CONF to define its configuration parameters and those types. + - DEFAULT to provide default values for each configuration parameters. + +#. It must define a global variable RULES_MAP to provide mappings of rule ID + and rule modules to yamllint like this. + :: + + RULES_MAP = { + # rule ID: rule module + a_custom_rule.ID: a_custom_rule + } + +To develop yamllint rules, the default rules themselves in yamllint may become +good references.