docs: Add documentation for Configurable Warnings

This includes detailing the use of `fatal-warnings` within project.conf

1 files changed, 18 insertions, 1 deletions

diff --git a/buildstream/plugin.py b/buildstream/plugin.py
index 64b38ff99..4514ee355 100644
--- a/buildstream/plugin.py
+++ b/buildstream/plugin.py
@@ -47,6 +47,23 @@ it is mandatory to implement the following abstract methods:
   Once all configuration has been loaded and preflight checks have passed,
   this method is used to inform the core of a plugin's unique configuration.
 
+Configurable Warnings
+---------------------
+Warnings raised through calling :func:`Plugin.warn() <buildstream.plugin.Plugin.warn>` can provide an optional
+parameter ``warning_token``, this will raise a :class:`PluginError` if the warning is configured as fatal within
+the project configuration.
+
+Configurable warnings will be prefixed with :func:`Plugin.get_kind() <buildstream.plugin.Plugin.get_kind>`
+within buildstream and must be prefixed as such in project configurations. For more detail on project configuration
+see :ref:`Configurable Warnings <configurable_warnings>`.
+
+It is important to document these warnings in your plugin documentation to allow users to make full use of them
+while configuring their projects.
+
+Example
+~~~~~~~
+If the :class:`git <buildstream.plugins.sources.git.GitSource>` plugin uses the warning ``"inconsistent-submodule"``
+then it could be referenced in project configuration as ``"git:inconsistent-submodule"``.
 
 Plugin Structure
 ----------------
@@ -731,7 +748,7 @@ class CoreWarnings():
     OVERLAPS = "overlaps"
     """
     This warning will be produced when buildstream detects an overlap on an element
-        which is not whitelisted.
+        which is not whitelisted. See :ref:`Overlap Whitelist <public_overlap_whitelist>`
     """
 
     REF_NOT_IN_TRACK = "ref-not-in-track"