Docs: Add Deprecations docs

Author: BeyondEvil

.github/workflows/tests.yml

@@ -12,7 +12,7 @@ on:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref != github.event.repository.default_branch }}
+  cancel-in-progress: ${{ ! contains(github.ref, github.event.repository.default_branch) }}
 
 jobs:
   build_docs:

docs/deprecations.rst

@@ -0,0 +1,165 @@
+User Guide
+==========
+
+Deprecation policy
+------------------
+
+If not otherwise explicitly stated, deprecations are removed in the next major version.
+
+Deprecations
+-------------------------------------
+
+duration_formatter
+~~~~~~~~~~~~~~~~~~
+
+Deprecated in ``4.0.0``
+
+*'duration_formatter' has been removed and no longer has any effect!*
+
+Reason
+^^^^^^
+
+With the rewrite of the plugin where most of the logic was moved to javascript,
+the disconnect between time formatting between python and javascript made it
+untenable to support dynamically setting the format.
+
+The decision was made to have ``ms`` for durations under 1 second,
+and ``HH:mm:ss`` for 1 second and above.
+
+Mitigation
+^^^^^^^^^^
+
+Currently none.
+
+render_collapsed
+~~~~~~~~~~~~~~~~
+
+Deprecated in ``4.0.0``
+
+*'render_collapsed = True' is deprecated and support will be removed in the next major release.
+Please use 'render_collapsed = all' instead.*
+
+Reason
+^^^^^^
+
+We've changed the ini-config to better match the query param, so now the ini-config takes the same
+values as the query param. For valid values please see :ref:`render-collapsed`.
+
+Mitigation
+^^^^^^^^^^
+
+Setting ``render_collapsed`` to ``all`` is equivalent to previously setting it to ``True``.
+
+.. _report-extra:
+
+report.extra
+~~~~~~~~~~~~
+
+Deprecated in ``4.0.0``
+
+*The 'report.extra' attribute is deprecated and will be removed in a future release,
+use 'report.extras' instead.*
+
+Reason
+^^^^^^
+
+The ``extra`` attribute is of type ``list``, hence more appropriately named ``extras``.
+
+Mitigation
+^^^^^^^^^^
+
+Rename ``extra`` to ``extras``.
+
+extra fixture
+~~~~~~~~~~~~~
+
+Deprecated in ``4.0.0``
+
+*The 'extra' fixture is deprecated and will be removed in a future release,
+use 'extras' instead.*
+
+Reason
+^^^^^^
+
+See :ref:`report-extra`
+
+Mitigation
+^^^^^^^^^^
+
+Rename ``extra`` to ``extras``.
+
+cell list assignment
+~~~~~~~~~~~~~~~~~~~~
+
+Deprecated in ``4.0.0``
+
+*list-type assignment is deprecated and support will be removed in a future release.
+Please use 'insert()' instead.*
+
+Reason
+^^^^^^
+
+The `cells` argument in the table manipulation hooks (see :ref:`modifying-results-table`) was
+previously of type `list` but is now an object.
+
+Mitigation
+^^^^^^^^^^
+
+Replace ``cells[4] = value`` with ``cells.insert(4, value)``.
+
+py module
+~~~~~~~~~
+
+Deprecated in ``4.0.0``
+
+*The 'py' module is deprecated and support will be removed in a future release.*
+
+Reason
+^^^^^^
+
+The ``py`` module is in maintenance mode and has been removed as a dependency.
+
+Mitigation
+^^^^^^^^^^
+
+Any usage of the ``html`` module from ``py.xml``, should be replaced with something
+that returns the HTML as a string.
+
+From:
+
+.. code-block:: python
+
+  import pytest
+  from py.xml import html
+
+
+  def pytest_html_results_table_header(cells):
+      cells.insert(2, html.th("Description"))
+      cells.insert(
+          1, html.th("Time", class_="sortable time", data - column - type="time")
+      )
+
+To:
+
+.. code-block:: python
+
+  import pytest
+
+
+  def pytest_html_results_table_header(cells):
+      cells.insert(2, "<th>Description</th>")
+      cells.insert(1, '<th class="sortable time" data-column-type="time">Time</th>')
+
+Note that you can keep using the `py` module by simple wrapping it in ``str``:
+
+.. code-block:: python
+
+  import pytest
+  from py.xml import html
+
+
+  def pytest_html_results_table_header(cells):
+      cells.insert(2, str(html.th("Description")))
+      cells.insert(
+          1, str(html.th("Time", class_="sortable time", data - column - type="time"))
+      )

docs/index.rst

@@ -17,5 +17,6 @@ pytest-html is a plugin for `pytest`_ that generates a HTML report for test resu
    api_reference
    development
    changelog
+   deprecations
 
 .. _pytest: http://pytest.org

docs/user_guide.rst

@@ -102,28 +102,25 @@ You can edit the *Summary* section by using the :code:`pytest_html_results_summa
 
 .. code-block:: python
 
-   from py.xml import html
-
-
    def pytest_html_results_summary(prefix, summary, postfix):
        prefix.extend(["<p>foo: bar</p>"])
 
 Extra content
 ~~~~~~~~~~~~~
 
-You can add details to the HTML report by creating an 'extra' list on the
+You can add details to the HTML report by creating an 'extras' list on the
 report object. Here are the types of extra content that can be added:
 
 ==========  ============================================
 Type        Example
 ==========  ============================================
-Raw HTML    ``extra.html('<div>Additional HTML</div>')``
-`JSON`_     ``extra.json({'name': 'pytest'})``
-Plain text  ``extra.text('Add some simple Text')``
-URL         ``extra.url('http://www.example.com/')``
-Image       ``extra.image(image, mime_type='image/gif', extension='gif')``
-Image       ``extra.image('/path/to/file.png')``
-Image       ``extra.image('http://some_image.png')``
+Raw HTML    ``extras.html('<div>Additional HTML</div>')``
+`JSON`_     ``extras.json({'name': 'pytest'})``
+Plain text  ``extras.text('Add some simple Text')``
+URL         ``extras.url('http://www.example.com/')``
+Image       ``extras.image(image, mime_type='image/gif', extension='gif')``
+Image       ``extras.image('/path/to/file.png')``
+Image       ``extras.image('http://some_image.png')``
 ==========  ============================================
 
 **Note**: When adding an image from file, the path can be either absolute
@@ -138,9 +135,9 @@ There are also convenient types for several image formats:
 ============  ====================
 Image format  Example
 ============  ====================
-PNG           ``extra.png(image)``
-JPEG          ``extra.jpg(image)``
-SVG           ``extra.svg(image)``
+PNG           ``extras.png(image)``
+JPEG          ``extras.jpg(image)``
+SVG           ``extras.svg(image)``
 ============  ====================
 
 The following example adds the various types of extras using a
@@ -150,42 +147,44 @@ conftest.py file:
 .. code-block:: python
 
   import pytest
+  import pytest_html
 
 
   @pytest.hookimpl(hookwrapper=True)
   def pytest_runtest_makereport(item, call):
-      pytest_html = item.config.pluginmanager.getplugin("html")
       outcome = yield
       report = outcome.get_result()
-      extra = getattr(report, "extra", [])
+      extras = getattr(report, "extras", [])
       if report.when == "call":
           # always add url to report
-          extra.append(pytest_html.extras.url("http://www.example.com/"))
+          extras.append(pytest_html.extras.url("http://www.example.com/"))
           xfail = hasattr(report, "wasxfail")
           if (report.skipped and xfail) or (report.failed and not xfail):
               # only add additional html on failure
-              extra.append(pytest_html.extras.html("<div>Additional HTML</div>"))
-          report.extra = extra
+              extras.append(pytest_html.extras.html("<div>Additional HTML</div>"))
+          report.extras = extras
 
 You can also specify the :code:`name` argument for all types other than :code:`html` which will change the title of the
 created hyper link:
 
 .. code-block:: python
 
-    extra.append(pytest_html.extras.text("some string", name="Different title"))
+    extras.append(pytest_html.extras.text("some string", name="Different title"))
 
-It is also possible to use the fixture :code:`extra` to add content directly
+It is also possible to use the fixture :code:`extras` to add content directly
 in a test function without implementing hooks. These will generally end up
 before any extras added by plugins.
 
 .. code-block:: python
 
-   from pytest_html import extras
+   import pytest_html
+
 
+   def test_extra(extras):
+       extras.append(pytest_html.extras.text("some string"))
 
-   def test_extra(extra):
-       extra.append(extras.text("some string"))
 
+.. _modifying-results-table:
 
 Modifying the results table
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -196,7 +195,6 @@ adds a sortable time column, and removes the links column:
 
 .. code-block:: python
 
-  from datetime import datetime
   import pytest
 
 
@@ -232,9 +230,6 @@ additional HTML and log output with a notice that the log is empty:
 
 .. code-block:: python
 
-  from py.xml import html
-
-
   def pytest_html_results_table_html(report, data):
       if report.passed:
           del data[:]
@@ -243,6 +238,8 @@ additional HTML and log output with a notice that the log is empty:
 Display options
 ---------------
 
+.. _render-collapsed:
+
 Auto Collapsing Table Rows
 ~~~~~~~~~~~~~~~~~~~~~~~~~~