What is needed for "Books" compatible reports?

Development
1

What needs to be checked to make certain that a Report is compatible with the Books feature?

I started tweaking the Descendants Books addon report and discovered those reports weren’t listed in the Books interface. Added REPORT_MODE_BKI to the report_modes registry item and it seems to save options and stylesheet data.

But is there anything else that should be checked?

    report_modes = [REPORT_MODE_GUI, REPORT_MODE_BKI, REPORT_MODE_CLI],

4

When attempt to use the Books feature to output a SuperTool Scripts compilation list with a Cover sheet, Table of Contents and Notes report.

The attempt failed with error messages.

Looking for a list of criteria and process for making Books compatible Reports was similarly unsuccessful locating a wiki article or Sphinx article. And this topic has had no responses.

So added a placeholder “See also” entry to the Books wiki section. Which should eventually be linked to a Developers/Design category article.

Then asked Perplexity to compose a draft to be human-edited and then posted as that article. It will be the next posting and be made into a wiki for collaborative editing.

5

Perplexity prompt:

as an expert in Python and Gramps genealogical software’s source code, describe what is necessary to make a “Report” addon plugin compatible with the “Book” collated report generator. Note any specific unit tests to verify compatibility.
To make a “Report” addon plugin compatible with the “Books” collated report generator in Gramps, you need to consider several key aspects:

  1. Report Class Structure:

    • Ensure your report class inherits from the appropriate base class, typically gramps.gen.plug.report.Report.
    • Implement the write_report() method, which is called by the Book generator.

  2. Option Class:

    • Create an option class that inherits from gramps.gen.plug.menu.MenuReportOptions.
    • Define all necessary options for your report in the add_menu_options() method.

  3. Report Modes:

    • Support multiple report modes, especially REPORT_MODE_BKI (Book Include mode).
    • In your .gpr.py file, include REPORT_MODE_BKI in the report_modes list:
      report_modes = [REPORT_MODE_GUI, REPORT_MODE_CLI, REPORT_MODE_BKI]

  4. Handling Book Context:

    • In your write_report() method, check for the book context:
      if self.doc.doc.book_mode:
    # Adjust report behavior for book inclusion

  5. Document Handling:

    • Use the provided self.doc object for all document operations.
    • Avoid creating new pages or sections unless necessary for your report’s structure.

  6. Localization:

    • Ensure all user-visible strings are properly localized using the _() function.

  7. Error Handling:

    • Implement robust error handling to prevent crashes during book generation.

  8. Performance Considerations:

    • Optimize your report for efficiency, as it may be called multiple times in a book.

Unit Tests for Book Compatibility:

  1. Test Book Mode Detection:

    def test_book_mode_detection(self):
    # Mock a book context
    # Verify that the report behaves correctly in book mode

  2. Test Option Handling:

    def test_book_options(self):
    # Verify that all options are properly handled in book context

  3. Test Document Structure:

    def test_document_structure_in_book(self):
    # Ensure the report doesn't create unnecessary pages/sections in book mode

  4. Test Error Handling:

    def test_error_handling_in_book(self):
    # Simulate various error conditions
    # Verify that errors are handled gracefully without crashing the book generation

  5. Test Localization in Book Context:

    def test_localization_in_book(self):
    # Verify that all strings are properly localized when included in a book

  6. Performance Test:

    def test_performance_in_book(self):
    # Measure the execution time of the report in book mode
    # Compare it with standalone mode to ensure no significant performance degradation

  7. Test Multiple Instances:

    def test_multiple_instances_in_book(self):
    # Simulate including the report multiple times in a book
    # Verify that each instance behaves correctly and independently

By implementing these features and running these unit tests, you can ensure that your Report addon plugin is compatible with the Book collated report generator in Gramps. This will provide a seamless experience for users who want to include your report in their book compilations.

Citations:
[1] Discourse: Need help getting started with a new addon
[2] Discourse: What is needed for "Books" compatible reports?
[3] 5.2 Addons - Gramps
[4] GitHub - gramps-project/addons: Third-party plugins for Gramps genealogy program
[5] Reddit: gramps/comments/gpccyk/best_reports_to_run