More docs on registering marks

changelog/4935.doc.rst

@@ -0,0 +1 @@
+Expand docs on registering marks and the effect of ``--strict``.

doc/en/mark.rst

@@ -26,12 +26,10 @@ which also serve as documentation.
     :ref:`fixtures <fixtures>`.
 
 
-Raising errors on unknown marks: --strict
------------------------------------------
+.. _unknown-marks:
 
-When the ``--strict`` command-line flag is passed, any unknown marks applied
-with the ``@pytest.mark.name_of_the_mark`` decorator will trigger an error.
-Marks defined or added by pytest or by a plugin will not trigger an error.
+Raising errors on unknown marks
+-------------------------------
 
 Marks can be registered in ``pytest.ini`` like this:
 
@@ -42,8 +40,10 @@ Marks can be registered in ``pytest.ini`` like this:
         slow
         serial
 
-This can be used to prevent users mistyping mark names by accident. Test suites that want to enforce this
-should add ``--strict`` to ``addopts``:
+When the ``--strict`` command-line flag is passed, any unknown marks applied
+with the ``@pytest.mark.name_of_the_mark`` decorator will trigger an error.
+Marks added by pytest or by a plugin instead of the decorator will not trigger
+this error.  To enforce a limited set of markers, add ``--strict`` to ``addopts``:
 
 .. code-block:: ini
 
@@ -53,6 +53,9 @@ should add ``--strict`` to ``addopts``:
         slow
         serial
 
+Third-party plugins should always :ref:`register their markers <registering-markers>`
+so that they appear in pytest's help text and do not emit warnings.
+
 
 .. _marker-revamp:
 

doc/en/writing_plugins.rst

@@ -286,6 +286,26 @@ the plugin manager like this:
 If you want to look at the names of existing plugins, use
 the ``--trace-config`` option.
 
+
+.. _registering-markers:
+
+Registering custom markers
+--------------------------
+
+If your plugin uses any markers, you should register them so that they appear in
+pytest's help text and do not :ref:`cause spurious warnings <unknown-marks>`.
+For example, the following plugin would register ``cool_marker`` and
+``mark_with`` for all users:
+
+.. code-block:: python
+
+    def pytest_configure(config):
+        config.addinivalue_line("markers", "cool_marker: this one is for cool tests.")
+        config.addinivalue_line(
+            "markers", "mark_with(arg, arg2): this marker takes arguments."
+        )
+
+
 Testing plugins
 ---------------