Documentation - Refine the adding reports page

- Move all generic (page/non-page) class references to the top of the documentation
- Use better heading level nesting cleanly isolate the full page report example
- Relates to #12428

CHANGELOG.txt

@@ -8,6 +8,7 @@ Changelog
  * Docs: Move the model reference page from reference/pages to the references section as it covers all Wagtail core models (Srishti Jaiswal)
  * Docs: Move the panels reference page from references/pages to the references section as panels are available for any model editing, merge panels API into this page (Srishti Jaiswal)
  * Docs: Move the tags documentation to standalone advanced topic, instead of being inside the reference/pages section (Srishti Jaiswal)
+ * Docs: Refine the adding reports page so that common (page/non-page) class references are at the top and the full page only example has correct heading nesting (Alessandro Chitarrini)
 
 
 6.3 LTS (xx.xx.xxxx) - IN DEVELOPMENT

CONTRIBUTORS.md

@@ -848,6 +848,7 @@
 * Shaurya Panchal
 * Sumana Sree Angajala
 * Srishti Jaiswal
+* Alessandro Chitarrini
 
 ## Translators
 

docs/extending/adding_reports.md

@@ -2,26 +2,17 @@
 
 # Adding reports
 
-Reports are views with listings of pages matching a specific query. They can also export these listings in spreadsheet format.
+Reports are views with listings of pages or any non-page model (such as snippets) matching a specific query. Reports can also export these listings in spreadsheet format.
 They are found in the _Reports_ submenu: by default, the _Locked pages_ report is provided, allowing an overview of locked pages on the site.
 
-It is possible to create your own custom reports in the Wagtail admin. Two base classes are provided:
-`wagtail.admin.views.reports.ReportView`, which provides basic listing and spreadsheet export functionality, and
-`wagtail.admin.views.reports.PageReportView`, which additionally provides a default set of fields suitable for page listings.
-For this example, we'll add a report which shows any pages with unpublished changes.
-We will register this view using the `unpublished_changes_report` name for the URL pattern.
-
-```python
-# <project>/views.py
-from wagtail.admin.views.reports import PageReportView
+It is possible to create your own custom reports in the Wagtail admin with two base classes provided:
 
+-   `wagtail.admin.views.reports.ReportView` - Provides the basic listing (with a single column) and spreadsheet export functionality.
+-   `wagtail.admin.views.reports.PageReportView` - Extends the `ReportView` and provides a default set of fields suitable for page listings.
 
-class UnpublishedChangesReportView(PageReportView):
-    index_url_name = "unpublished_changes_report"
-    index_results_url_name = "unpublished_changes_report_results"
-```
+## Reporting reference
 
-## Defining your report
+### `get_queryset`
 
 The most important attributes and methods to customize to define your report are:
 
@@ -29,21 +20,34 @@ The most important attributes and methods to customize to define your report are
 .. method:: get_queryset(self)
 ```
 
-This retrieves the queryset of pages for your report. For our example:
+This retrieves the queryset of pages or other models for your report, two examples below.
 
 ```python
 # <project>/views.py
 
-from wagtail.admin.views.reports import PageReportView
+from wagtail.admin.views.reports import ReportView, PageReportView
 from wagtail.models import Page
 
+from .models import MySnippetModel
+
 
 class UnpublishedChangesReportView(PageReportView):
+    # includes common page fields by default
 
     def get_queryset(self):
         return Page.objects.filter(has_unpublished_changes=True)
+
+
+class CustomModelReport(ReportView):
+    # includes string representation as a single column only
+
+    def get_queryset(self):
+        return MySnippetModel.objects.all()
+
 ```
 
+### Other attributes
+
 ```{eval-rst}
 
 .. attribute:: template_name
@@ -96,7 +100,7 @@ The name of the URL pattern registered for the results view (the report view wit
 
 ```
 
-## Spreadsheet exports
+### Spreadsheet exports
 
 ```{eval-rst}
 
@@ -143,7 +147,21 @@ preprocessing, set the preprocessing_function to ``None``.
 
 ```
 
-## Customizing templates
+## Example report for pages with unpublished changes
+
+For this example, we'll add a report which shows any pages with unpublished changes.
+We will register this view using the `unpublished_changes_report` name for the URL pattern.
+
+```python
+# <project>/views.py
+from wagtail.admin.views.reports import PageReportView
+
+class UnpublishedChangesReportView(PageReportView):
+    index_url_name = "unpublished_changes_report"
+    index_results_url_name = "unpublished_changes_report_results"
+```
+
+### Customizing templates
 
 For this example \"pages with unpublished changes\" report, we'll add an extra column to the listing template, showing the last publication date for each page. To do this, we'll extend two templates: `wagtailadmin/reports/base_page_report_results.html`, and `wagtailadmin/reports/listing/_list_page_report.html`.
 
@@ -179,7 +197,7 @@ For this example \"pages with unpublished changes\" report, we'll add an extra c
 
 Finally, we'll set `UnpublishedChangesReportView.results_template_name` to this new template: `'reports/unpublished_changes_report_results.html'`.
 
-## Adding a menu item and admin URL
+### Adding a menu item and admin URL
 
 To add a menu item for your new report to the _Reports_ submenu, you will need to use the `register_reports_menu_item` hook (see: [Register Reports Menu Item](register_reports_menu_item)). To add an admin url for the report, you will need to use the `register_admin_urls` hook (see: [Register Admin URLs](register_admin_urls)). This can be done as follows:
 
@@ -208,7 +226,7 @@ def register_unpublished_changes_report_url():
 
 Here, we use the `AdminOnlyMenuItem` class to ensure our report icon is only shown to superusers. To make the report visible to all users, you could replace this with `MenuItem`.
 
-## Setting up permission restriction
+### Setting up permission restriction
 
 Even with the menu item hidden, it would still be possible for any user to visit the report's URL directly, and so it is necessary to set up a permission restriction on the report view itself. This can be done by adding a `dispatch` method to the existing `UnpublishedChangesReportView` view:
 
@@ -221,7 +239,7 @@ Even with the menu item hidden, it would still be possible for any user to visit
         return super().dispatch(request, *args, **kwargs)
 ```
 
-## The full code
+### The full code
 
 ```python
 # <project>/views.py

docs/releases/6.4.md

@@ -25,6 +25,7 @@ depth: 1
  * Move the [model reference page](../reference/models.md) from reference/pages to the references section as it covers all Wagtail core models (Srishti Jaiswal)
  * Move the [panels reference page](../reference/panels.md) from references/pages to the references section as panels are available for any model editing, merge panels API into this page (Srishti Jaiswal)
  * Move the tags documentation to standalone [advanced topic for tagging](../advanced_topics/tags.md), instead of being inside the reference/pages section (Srishti Jaiswal)
+ * Refine the [](adding_reports) page so that common (page/non-page) class references are at the top and the full page only example has correct heading nesting (Alessandro Chitarrini)
 
 ### Maintenance