[ADD] util/report: util.add_report

[diagnoza]

Add a new function that replaces util.add_to_migration_reports.

The new function can automatically parse the provided data as a list of records. It can also limit the number of displayed records to prevent the upgrade report from growing too large.

The structure of the note is now defined within the function itself, standardizing its appearance.

Example usage

More examples will follow in odoo/upgrade, replacing the existing use of util.add_to_migration_reports.

Example 1

cr.execute(
        """
        SELECT p.id, p.name, p.city, p.comment, p.company_id, com.name FROM res_partner p
          JOIN res_company com
            ON p.company_id = com.id
        """
    )

summary = """
    This is a test of the utility method that is displaying a list of rows
    returned by an SQL query. The number of displayed rows is limited.
    """
row_format = "Partner with id {partner_link} works at company {company_link} in {city}, ({comment})"
columns = ("id", "name", "city", "comment", "company_id", "company_name")
links = {"company_link": ("res.company", "company_id", "company_name"), "partner_link": ("res.partner", "id", "name")}
util.add_report(header="Test of the new utility method", summary=summary, row_format=row_format, columns=columns, links=links, data=cr.fetchall())

Example 2

util.add_report(header="Simple note", summary="A detailed description of the change.")

Example 3

msg = """
This is some text in **bold**.  

This is a line  
that should break.

- Item one
- Item two
    - Sub-item

And some _italic_ text.
"""
util.add_report(header="MD note", summary=msg, report_format="md")

Example 4

msg = """
This is some text in **bold**.

| This is a line
| that should break.

* Item one
* Item two

  * Sub-item

And some *italic* text.
"""
util.add_report(header="RST note", summary=msg, report_format="rst")

Remaining details to discuss

1. The introduction of env var to control limit.
2. Enforce/assert the use of tuples instead of lists. Currently, it's possible to pass a list for columns (instead of a tuple) or a dictionary of lists for links (instead of a dictionary of tuples).
3. How to handle depreciation of add_to_migration_reports.
4. Indentation of the ir.ui.view record corresponding to the note is sometimes incorrect (previously there was the same issue):

[robodoo]

[KangOl]

upgradeci retry with always only crm

[aj-fuentes]

I think we can do some simplification here. Some suggestions below. Note that none of the suggestions were tested, take it as a guide.

[aj-fuentes]

• Do not use typing format, follow what's done elsewhere in this repo and use the plain type built-ins
• Shorten this and move all examples to a proper example block in the documentation description before the parameters:

.. example::

  .. code-block:: python

    # code example here

• Always ensure everything renders as expected -> open the documentation CI link, then log in and go to the relevant section of the documentation. This would need a PR in odoo/documentation to add the automodule for util.report and will require revision of all other functions we document here. Target 17.0
• Document the parameters in the same order they are used in the function.
• Use lowercase after the colon (basically follow the format as in other cases here ;))

Some of the above as a suggestion:

Suggested change

	:param List[Tuple] data: Any data in the form of a list of tuples, e.g. the output of cr.fetchall().
	:param Tuple[str] columns: Arbitrary names for each column in "data". All columns must be named and
	the order of these names must be the same as in "data".
	:param Dict[str, Tuple[str, str, str]] links: Optional model/record links, e.g.:
	{
	"partner_link": ("res.partner", "id", "name"),
	"company_link": ("res.company", "company_id", "company_name"),
	}
	:param list(tuple) data: data to report, each entry would be a row in the report.
	It could be empty, in which case only the summary is redered.
	:param tuple(str) columns: names for each column in "data", can be referenced in `row_format`.
	:param dict links: optional model/record links spec, the keys can be referenced in `row_format`.

[aj-fuentes]

Maybe this is better:

Suggested change

	return report_with_summary(summary=summary, details="No records to display.", category=category)
	return report_with_summary(summary=summary, details="", category=category)

then adapt report_with_summary to not add any summary/details structure when details is empty, and just output summary directly.

[aj-fuentes]

Looks better. Please adapt the documentation to the same format we use elsewhere in this repo. Some suggestions above.