[1.8.x] Fixed #25174 -- Moved some details of CheckMessage to the reference guide.

Backport of faa2a0f662 from master

docs/ref/checks.txt

@@ -4,6 +4,8 @@ System check framework
 
 .. versionadded:: 1.7
 
+.. currentmodule:: django.core.checks
+
 The system check framework is a set of static checks for validating Django
 projects. It detects common problems and provides hints for how to fix them.
 The framework is extensible so you can easily add your own checks.
@@ -11,6 +13,64 @@ The framework is extensible so you can easily add your own checks.
 For details on how to add your own checks and integrate them with Django's
 system checks, see the :doc:`System check topic guide </topics/checks>`.
 
+API Reference
+=============
+
+``CheckMessage``
+-----------------
+
+.. class:: CheckMessage(level, msg, hint, obj=None, id=None)
+
+The warnings and errors raised by system checks must be instances of
+``CheckMessage``. An instance encapsulates a single reportable error or
+warning. It also provides context and hints applicable to the message, and a
+unique identifier that is used for filtering purposes.
+
+Constructor arguments are:
+
+``level``
+    The severity of the message. Use one of the predefined values: ``DEBUG``,
+    ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``. If the level is greater or
+    equal to ``ERROR``, then Django will prevent management commands from
+    executing. Messages with level lower than ``ERROR`` (i.e. warnings) are
+    reported to the console, but can be silenced.
+
+``msg``
+    A short (less than 80 characters) string describing the problem. The string
+    should *not* contain newlines.
+
+``hint``
+    A single-line string providing a hint for fixing the problem. If no hint
+    can be provided, or the hint is self-evident from the error message, the
+    hint can be omitted, or a value of ``None`` can be used.
+
+``obj``
+    Optional. An object providing context for the message (for example, the
+    model where the problem was discovered). The object should be a model,
+    field, or manager or any other object that defines ``__str__`` method (on
+    Python 2 you need to define ``__unicode__`` method). The method is used
+    while reporting all messages and its result precedes the message.
+
+``id``
+    Optional string. A unique identifier for the issue. Identifiers should
+    follow the pattern ``applabel.X001``, where ``X`` is one of the letters
+    ``CEWID``, indicating the message severity (``C`` for criticals, ``E`` for
+    errors and so). The number can be allocated by the application, but should
+    be unique within that application.
+
+There are subclasses to make creating messages with common levels easier. When
+using them you can omit the ``level`` argument because it is implied by the
+class name.
+
+.. class:: Debug(msg, hint, obj=None, id=None)
+.. class:: Info(msg, hint, obj=None, id=None)
+.. class:: Warning(msg, hint, obj=None, id=None)
+.. class:: Error(msg, hint, obj=None, id=None)
+.. class:: Critical(msg, hint, obj=None, id=None)
+
+Builtin checks
+==============
+
 Builtin tags
 ------------
 

docs/topics/checks.txt

@@ -31,12 +31,21 @@ The framework is flexible and allows you to write functions that perform
 any other kind of check you may require. The following is an example stub
 check function::
 
-    from django.core.checks import register
+    from django.core.checks import Error, register
 
     @register()
     def example_check(app_configs, **kwargs):
         errors = []
         # ... your check logic here
+        if check_failed:
+            errors.append(
+                Error(
+                    'an error',
+                    hint=None,
+                    obj=checked_object,
+                    id='myapp.E001',
+                )
+            )
         return errors
 
 The check function *must* accept an ``app_configs`` argument; this argument is
@@ -50,75 +59,25 @@ Messages
 The function must return a list of messages. If no problems are found as a result
 of the check, the check function must return an empty list.
 
-.. class:: CheckMessage(level, msg, hint, obj=None, id=None)
-
 The warnings and errors raised by the check method must be instances of
 :class:`~django.core.checks.CheckMessage`. An instance of
 :class:`~django.core.checks.CheckMessage` encapsulates a single reportable
 error or warning. It also provides context and hints applicable to the
 message, and a unique identifier that is used for filtering purposes.
 
-The concept is very similar to messages from the :doc:`message
+The concept is very similar to messages from the :doc:`message framework
-framework </ref/contrib/messages>` or the :doc:`logging framework
+</ref/contrib/messages>` or the :doc:`logging framework </topics/logging>`.
-</topics/logging>`. Messages are tagged with a ``level`` indicating the
+Messages are tagged with a ``level`` indicating the severity of the message.
-severity of the message.
-
-Constructor arguments are:
-
-``level``
-    The severity of the message. Use one of the
-    predefined values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``,
-    ``CRITICAL``. If the level is greater or equal to ``ERROR``, then Django
-    will prevent management commands from executing. Messages with
-    level lower than ``ERROR`` (i.e. warnings) are reported to the console,
-    but can be silenced.
-
-``msg``
-    A short (less than 80 characters) string describing the problem. The string
-    should *not* contain newlines.
-
-``hint``
-    A single-line string providing a hint for fixing the problem. If no hint
-    can be provided, or the hint is self-evident from the error message, the
-    hint can be omitted, or a value of ``None`` can be used.
-
-``obj``
-    Optional. An object providing context for the message (for example, the
-    model where the problem was discovered). The object should be a model, field,
-    or manager or any other object that defines ``__str__`` method (on
-    Python 2 you need to define ``__unicode__`` method). The method is used while
-    reporting all messages and its result precedes the message.
-
-``id``
-    Optional string. A unique identifier for the issue. Identifiers should
-    follow the pattern ``applabel.X001``, where ``X`` is one of the letters
-    ``CEWID``, indicating the message severity (``C`` for criticals,
-    ``E`` for errors and so). The number can be allocated by the application,
-    but should be unique within that application.
 
 There are also shortcuts to make creating messages with common levels easier.
-When using these methods you can omit the ``level`` argument because it is
+When using these classes you can omit the ``level`` argument because it is
 implied by the class name.
 
-.. class:: Debug(msg, hint, obj=None, id=None)
+* :class:`Debug`
-.. class:: Info(msg, hint, obj=None, id=None)
+* :class:`Info`
-.. class:: Warning(msg, hint, obj=None, id=None)
+* :class:`Warning`
-.. class:: Error(msg, hint, obj=None, id=None)
+* :class:`Error`
-.. class:: Critical(msg, hint, obj=None, id=None)
+* :class:`Critical`
-
-Messages are comparable. That allows you to easily write tests::
-
-    from django.core.checks import Error
-    errors = checked_object.check()
-    expected_errors = [
-        Error(
-            'an error',
-            hint=None,
-            obj=checked_object,
-            id='myapp.E001',
-        )
-    ]
-    self.assertEqual(errors, expected_errors)
 
 Registering and labeling checks
 -------------------------------
@@ -234,3 +193,20 @@ the only difference is that the check is a classmethod, not an instance method::
             errors = super(MyModel, cls).check(**kwargs)
             # ... your own checks ...
             return errors
+
+Writing Tests
+-------------
+
+Messages are comparable. That allows you to easily write tests::
+
+    from django.core.checks import Error
+    errors = checked_object.check()
+    expected_errors = [
+        Error(
+            'an error',
+            hint=None,
+            obj=checked_object,
+            id='myapp.E001',
+        )
+    ]
+    self.assertEqual(errors, expected_errors)