fix: skip global report caption when using a module (#1379)

* fix: skip global report caption when using a module

* do not overwrite existing report text

* Better error messages for failures when rendering report captions.

snakemake/modules.py

@@ -69,14 +69,21 @@ def __init__(
         self.replace_prefix = replace_prefix
         self.prefix = prefix
 
-    def use_rules(self, rules=None, name_modifier=None, ruleinfo=None):
+    def use_rules(
+        self,
+        rules=None,
+        name_modifier=None,
+        ruleinfo=None,
+        skip_global_report_caption=False,
+    ):
         snakefile = self.get_snakefile()
         with WorkflowModifier(
             self.workflow,
             config=self.config,
             base_snakefile=snakefile,
             skip_configfile=self.config is not None,
             skip_validation=self.skip_validation,
+            skip_global_report_caption=skip_global_report_caption,
             rule_whitelist=self.get_rule_whitelist(rules),
             rulename_modifier=get_name_modifier_func(rules, name_modifier),
             ruleinfo_overwrite=ruleinfo,
@@ -129,6 +136,7 @@ def __init__(
         base_snakefile=None,
         skip_configfile=False,
         skip_validation=False,
+        skip_global_report_caption=False,
         rulename_modifier=None,
         rule_whitelist=None,
         ruleinfo_overwrite=None,
@@ -150,6 +158,7 @@ def __init__(
         self.skip_configfile = skip_configfile
         self.rulename_modifier = rulename_modifier
         self.skip_validation = skip_validation
+        self.skip_global_report_caption = skip_global_report_caption
         self.rule_whitelist = rule_whitelist
         self.ruleinfo_overwrite = ruleinfo_overwrite
         self.allow_rule_overwrite = allow_rule_overwrite

snakemake/report/__init__.py

@@ -506,7 +506,10 @@ def render(self, env, rst_links, categories, files):
                 )
             except Exception as e:
                 raise WorkflowError(
-                    "Error loading caption file of output marked for report.", e
+                    "Error loading caption file {} of output marked for report.".format(
+                        self.raw_caption.get_path_or_uri()
+                    ),
+                    e,
                 )
 
     @property
@@ -602,7 +605,7 @@ def get_resource_as_string(url):
 
 def auto_report(dag, path, stylesheet=None):
     try:
-        from jinja2 import Template, Environment, PackageLoader
+        from jinja2 import Template, Environment, PackageLoader, UndefinedError
     except ImportError as e:
         raise WorkflowError(
             "Python package jinja2 must be installed to create reports."
@@ -848,12 +851,20 @@ class Snakemake:
                 config = dag.workflow.config
 
             text = f.read() + rst_links
-            text = publish_parts(
-                env.from_string(text).render(
-                    snakemake=Snakemake, categories=results, files=files
-                ),
-                writer_name="html",
-            )["body"]
+            try:
+                text = publish_parts(
+                    env.from_string(text).render(
+                        snakemake=Snakemake, categories=results, files=files
+                    ),
+                    writer_name="html",
+                )["body"]
+            except UndefinedError as e:
+                raise WorkflowError(
+                    "Error rendering global report caption {}:".format(
+                        dag.workflow.report_text.get_path_or_uri()
+                    ),
+                    e,
+                )
 
     # record time
     now = "{} {}".format(datetime.datetime.now().ctime(), time.tzname[0])

snakemake/workflow.py

@@ -1289,7 +1289,8 @@ def pepschema(self, schema):
 
     def report(self, path):
         """Define a global report description in .rst format."""
-        self.report_text = self.current_basedir.join(path)
+        if not self.modifier.skip_global_report_caption:
+            self.report_text = self.current_basedir.join(path)
 
     @property
     def config(self):
@@ -1843,6 +1844,8 @@ def decorate(maybe_ruleinfo):
                     rules,
                     name_modifier,
                     ruleinfo=None if callable(maybe_ruleinfo) else maybe_ruleinfo,
+                    skip_global_report_caption=self.report_text
+                    is not None,  # do not overwrite existing report text via module
                 )
             else:
                 # local inheritance