[*SCH Print][Added] Title propagation also KiCad workaround

set-soft · set-soft · commit f5b2b5f6af16 · 2026-06-09T11:36:45.000-03:00
- `title_propagate`: The title is not only set for page 1 but also for all pages. - Global `schematic_sheet_name_workaround` to workaround SHEETNAME on page 1 See #933
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   for KiCad 6.
 - Schematic:
   - Support for SHEETNAME, SHEETFILE and SHEETPATH in the title block
+- Globals:
+  - `schematic_sheet_name_workaround` to workaround SHEETNAME on page 1
+    (See #933)
 - Variants:
   - pre_transform filter to KiCad variants
 - E/DRC:
@@ -35,6 +38,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `collect_images`: To just avoid collecting images, enabled by
     default when generating a CSV. Avoids unintended infinite loops.
     (See #931)
+- *SCH Print
+  - `title_propagate`: The title is not only set for page 1 but also for
+    all pages.
 
 ## Fixed
 - Warnings:
diff --git a/docs/samples/generic_plot.kibot.yaml b/docs/samples/generic_plot.kibot.yaml
@@ -1365,6 +1365,8 @@ outputs:
       # [string=''] Text used to replace the sheet title. %VALUE expansions are allowed.
       # If it starts with `+` the text is concatenated
       title: ''
+      # [boolean=false] When enabled we also set the title for all the sub-sheets
+      title_propagate: false
       # [string=''] Board variant to apply.
       # Not fitted components are crossed
       variant: ''
@@ -1900,6 +1902,8 @@ outputs:
       # [string=''] Text used to replace the sheet title. %VALUE expansions are allowed.
       # If it starts with `+` the text is concatenated
       title: ''
+      # [boolean=false] When enabled we also set the title for all the sub-sheets
+      title_propagate: false
       # [string=''] Board variant to apply.
       # Not fitted components are crossed
       variant: ''
@@ -4121,6 +4125,8 @@ outputs:
       # [string=''] Text used to replace the sheet title. %VALUE expansions are allowed.
       # If it starts with `+` the text is concatenated
       title: ''
+      # [boolean=false] When enabled we also set the title for all the sub-sheets
+      title_propagate: false
       # [string=''] Board variant to apply.
       # Not fitted components are crossed
       variant: ''
@@ -4401,6 +4407,8 @@ outputs:
       # [string=''] Text used to replace the sheet title. %VALUE expansions are allowed.
       # If it starts with `+` the text is concatenated
       title: ''
+      # [boolean=false] When enabled we also set the title for all the sub-sheets
+      title_propagate: false
       # [string=''] Board variant to apply.
       # Not fitted components are crossed
       variant: ''
@@ -4626,6 +4634,14 @@ outputs:
       # The 7.4 is the standard for lead-free (i.e. SAC305) for 63 Sn/37 Pb 8.4 is standard.
       # Used to compute solder paste usage
       alloy_specific_gravity: 7.4
+      # [string='auto'] [auto,yes,no] When enabled we look for outputs that can generate useful images.
+      # They are  `pdf_pcb_print`, `pcb_print`, `svg_pcb_print`, `pdf_sch_print`, `svg_sch_print`
+      # and may be others. They are executed in order to get their outputs and make them available
+      # using the `schematic_pdfs`, `schematic_svgs`, `layer_pdfs` and `layer_svgs` images.
+      # The problem is when a `pcb_print` output needs a table generated by a `report` output.
+      # This can lead to a 'chicken and the egg' problem.
+      # The `auto` option only enables the search when the output isn't a `csv`.
+      collect_images: 'auto'
       # [string='markdown'] Original format for the report conversion. Current templates are `markdown`. See `do_convert`
       convert_from: 'markdown'
       # [string='pdf'] Target format for the report conversion. See `do_convert`
@@ -5136,6 +5152,8 @@ outputs:
       # [string=''] Text used to replace the sheet title. %VALUE expansions are allowed.
       # If it starts with `+` the text is concatenated
       title: ''
+      # [boolean=false] When enabled we also set the title for all the sub-sheets
+      title_propagate: false
       # [string=''] Board variant to apply.
       # Not fitted components are crossed
       variant: ''
diff --git a/docs/source/Changelog.rst b/docs/source/Changelog.rst
@@ -31,6 +31,11 @@ Added
 
    -  Support for SHEETNAME, SHEETFILE and SHEETPATH in the title block
 
+-  Globals:
+
+   -  ``schematic_sheet_name_workaround`` to workaround SHEETNAME on
+      page 1 (See #933)
+
 -  Variants:
 
    -  pre_transform filter to KiCad variants
@@ -63,6 +68,11 @@ Added
       default when generating a CSV. Avoids unintended infinite loops.
       (See #931)
 
+-  \*SCH Print
+
+   -  ``title_propagate``: The title is not only set for page 1 but also
+      for all pages.
+
 Fixed
 -----
 
diff --git a/docs/source/configuration/outputs/DXF_SCH_PrintOptions.rst b/docs/source/configuration/outputs/DXF_SCH_PrintOptions.rst
@@ -34,6 +34,7 @@ DXF_SCH_PrintOptions parameters
    file is available.
 -  ``title`` :index:`: <pair: output - dxf_sch_print - options; title>` [:ref:`string <string>`] (default: ``''``) Text used to replace the sheet title. %VALUE expansions are allowed.
    If it starts with `+` the text is concatenated.
+-  ``title_propagate`` :index:`: <pair: output - dxf_sch_print - options; title_propagate>` [:ref:`boolean <boolean>`] (default: ``false``) When enabled we also set the title for all the sub-sheets.
 -  ``variant`` :index:`: <pair: output - dxf_sch_print - options; variant>` [:ref:`string <string>`] (default: ``''``) Board variant to apply.
    Not fitted components are crossed.
 
diff --git a/docs/source/configuration/outputs/HPGL_SCH_PrintOptions.rst b/docs/source/configuration/outputs/HPGL_SCH_PrintOptions.rst
@@ -36,6 +36,7 @@ HPGL_SCH_PrintOptions parameters
    file is available.
 -  ``title`` :index:`: <pair: output - hpgl_sch_print - options; title>` [:ref:`string <string>`] (default: ``''``) Text used to replace the sheet title. %VALUE expansions are allowed.
    If it starts with `+` the text is concatenated.
+-  ``title_propagate`` :index:`: <pair: output - hpgl_sch_print - options; title_propagate>` [:ref:`boolean <boolean>`] (default: ``false``) When enabled we also set the title for all the sub-sheets.
 -  ``variant`` :index:`: <pair: output - hpgl_sch_print - options; variant>` [:ref:`string <string>`] (default: ``''``) Board variant to apply.
    Not fitted components are crossed.
 
diff --git a/docs/source/configuration/outputs/PDF_SCH_PrintOptions.rst b/docs/source/configuration/outputs/PDF_SCH_PrintOptions.rst
@@ -34,6 +34,7 @@ PDF_SCH_PrintOptions parameters
    file is available.
 -  ``title`` :index:`: <pair: output - pdf_sch_print - options; title>` [:ref:`string <string>`] (default: ``''``) Text used to replace the sheet title. %VALUE expansions are allowed.
    If it starts with `+` the text is concatenated.
+-  ``title_propagate`` :index:`: <pair: output - pdf_sch_print - options; title_propagate>` [:ref:`boolean <boolean>`] (default: ``false``) When enabled we also set the title for all the sub-sheets.
 -  ``variant`` :index:`: <pair: output - pdf_sch_print - options; variant>` [:ref:`string <string>`] (default: ``''``) Board variant to apply.
    Not fitted components are crossed.
 
diff --git a/docs/source/configuration/outputs/PS_SCH_PrintOptions.rst b/docs/source/configuration/outputs/PS_SCH_PrintOptions.rst
@@ -34,6 +34,7 @@ PS_SCH_PrintOptions parameters
    file is available.
 -  ``title`` :index:`: <pair: output - ps_sch_print - options; title>` [:ref:`string <string>`] (default: ``''``) Text used to replace the sheet title. %VALUE expansions are allowed.
    If it starts with `+` the text is concatenated.
+-  ``title_propagate`` :index:`: <pair: output - ps_sch_print - options; title_propagate>` [:ref:`boolean <boolean>`] (default: ``false``) When enabled we also set the title for all the sub-sheets.
 -  ``variant`` :index:`: <pair: output - ps_sch_print - options; variant>` [:ref:`string <string>`] (default: ``''``) Board variant to apply.
    Not fitted components are crossed.
 
diff --git a/docs/source/configuration/outputs/SVG_SCH_PrintOptions.rst b/docs/source/configuration/outputs/SVG_SCH_PrintOptions.rst
@@ -34,6 +34,7 @@ SVG_SCH_PrintOptions parameters
    file is available.
 -  ``title`` :index:`: <pair: output - svg_sch_print - options; title>` [:ref:`string <string>`] (default: ``''``) Text used to replace the sheet title. %VALUE expansions are allowed.
    If it starts with `+` the text is concatenated.
+-  ``title_propagate`` :index:`: <pair: output - svg_sch_print - options; title_propagate>` [:ref:`boolean <boolean>`] (default: ``false``) When enabled we also set the title for all the sub-sheets.
 -  ``variant`` :index:`: <pair: output - svg_sch_print - options; variant>` [:ref:`string <string>`] (default: ``''``) Board variant to apply.
    Not fitted components are crossed.
 
diff --git a/docs/source/configuration/sup_globals.rst b/docs/source/configuration/sup_globals.rst
@@ -210,6 +210,10 @@
          The width of the text box will be the width of the image. |br|
          The text box must contain *kibot_image_X* where X is the output name. |br|
          This option configures the prefix used. If this option is empty no images will be pasted.
+      -  ``schematic_sheet_name_workaround`` :index:`: <pair: global options; schematic_sheet_name_workaround>` [:ref:`boolean <boolean>`] (default: ``false``) When printing a schematic the SHEETNAME variable is wrongly expanded for page 1.
+         This error is present in KiCad 9 and at least 10.0.3. |br|
+         This workaround makes KiBot expand it for page 1. You must use the `title` option to set
+         the desired title, i.e. `My Project - ${SHEETNAME}`.
       -  ``set_text_variables_before_output`` :index:`: <pair: global options; set_text_variables_before_output>` [:ref:`boolean <boolean>`] (default: ``false``) Run the `set_text_variables` preflight before running each output that involves variants.
          This can be used when a text variable uses the variant and you want to create more than
          one variant in the same run. Note that this could be slow because it forces a board
diff --git a/kibot/globals.py b/kibot/globals.py
@@ -463,6 +463,11 @@ def __init__(self):
             self.code_page_fallback = 'latin1'
             """ Code page to use when UTF-8 decode fails. Leave empty to just use ASCII and spaces for codes
                 outside ASCII """
+            self.schematic_sheet_name_workaround = False
+            """ When printing a schematic the SHEETNAME variable is wrongly expanded for page 1.
+                This error is present in KiCad 9 and at least 10.0.3.
+                This workaround makes KiBot expand it for page 1. You must use the `title` option to set
+                the desired title, i.e. `My Project - ${SHEETNAME}` """
         self.set_doc('filters', " [list(dict)=[]] KiBot and KiCost warnings to be ignored."
                                 " Add 1000 to KiCost warnings (WCnnn) ")
         self._filter_what = 'KiBot warnings'
diff --git a/kibot/gs.py b/kibot/gs.py
@@ -44,6 +44,7 @@ class pcbnew(object):
 KICAD5_SVG_SCALE = 116930/297002200
 # Characters we don't want in a file name
 INVALID_CHARS = r'[?%*:|"<>]'
+KICAD_DYNAMIC_VARS = {'VARIANT', 'VARIANT_DESC', 'SHEETNAME', 'SHEETPATH', 'SHEETFILE'}
 
 
 class GS(object):
@@ -216,6 +217,7 @@ class GS(object):
     global_set_text_variables_sheet_title = None
     global_set_text_variables_sheet_title_min = None
     global_set_text_variables_sheet_title_default = None
+    global_schematic_sheet_name_workaround = None
     global_silk_screen_color = None
     global_silk_screen_color_bottom = None
     global_silk_screen_color_top = None
@@ -547,7 +549,7 @@ def expand_text_variables(text, extra_vars=None):
                 value = os.environ.get(vname, None)
             if value is None:
                 value = '${'+vname+'}'
-                if vname not in {'VARIANT', 'VARIANT_DESC'}:  # These are dynamic
+                if vname not in KICAD_DYNAMIC_VARS:
                     logger.warning(W_UNKVAR+"Unknown text variable `{}`".format(vname))
             if match.start():
                 new_text += text[last:match.start()]
diff --git a/kibot/kicad/v6_sch.py b/kibot/kicad/v6_sch.py
@@ -2413,13 +2413,24 @@ def _fill_missing_title_block(self):
         if not self.title:
             self.title = os.path.splitext(os.path.basename(self.fname))[0]
 
+    def _get_sheet_name(self):
+        sheet_name = self.sheet_path_h.split('/')[-1]
+        return 'Root' if not sheet_name else sheet_name
+
+    def _get_extra_vars(self, forced=False):
+        """ Returns a dict with KiCad variables that are expanded for this particular sheet.
+            We use them to expand variables in the title block.
+            The force=True argument is used for the regular use.
+            We also use it to workaround a bug in KiCad CLI that fails to correctly expand
+            SHEETNAME for page 1 (KiCad 9/10.0.3) """
+        if forced or (GS.global_schematic_sheet_name_workaround and self.sheet_path_h == '/'):
+            return {'SHEETNAME': self._get_sheet_name(), 'SHEETPATH': self.sheet_path_h, 'SHEETFILE': self.fname_rel}
+        return {}
+
     def _get_title_block(self, items):
         if not isinstance(items, list):
             raise SchError('The title block is not a list')
-        sheet_name = self.sheet_path_h.split('/')[-1]
-        if not sheet_name:
-            sheet_name = 'Root'
-        extra_vars = {'SHEETNAME': sheet_name, 'SHEETPATH': self.sheet_path_h, 'SHEETFILE': self.fname_rel}
+        extra_vars = self._get_extra_vars(forced=True)
         for item in items:
             if not isinstance(item, list) or len(item) < 2 or not isinstance(item[0], Symbol):
                 raise SchError('Wrong title block entry ({})'.format(item))
@@ -2485,7 +2496,8 @@ def write_paper(self):
     def write_title_block(self):
         data = []
         if self.title_ori:
-            data += [_symbol('title', [self.title_ori]), Sep()]
+            title = self.title if GS.global_schematic_sheet_name_workaround and self.sheet_path_h == '/' else self.title_ori
+            data += [_symbol('title', [title]), Sep()]
         if self.date_ori:
             data += [_symbol('date', [self.date_ori]), Sep()]
         if self.revision_ori:
@@ -2765,12 +2777,42 @@ def _create_flat_name(self, sch):
     def get_title(self):
         return self.title_ori
 
-    def set_title(self, title):
+    def set_title(self, title, propagate=False):
         """ Used only to save a variant """
         old_title = self.title_ori
         self.title_ori = title
+        extra_vars = self._get_extra_vars()
+        self.title = GS.expand_text_variables(self.title_ori, extra_vars=extra_vars)
+        logger.debug(f"Changing title for {self.sheet_path_h}: `{old_title}` -> "
+                     f"`{self.title_ori}` [expanded `{self.title}`]")
         return old_title
 
+    def set_titles(self, title, olds=None):
+        """ Used only to save a variant """
+        old_title_ori = self.title_ori
+        old_title = self.title
+        self.title_ori = title
+        extra_vars = self._get_extra_vars()
+        self.title = GS.expand_text_variables(self.title_ori, extra_vars=extra_vars)
+        logger.debug(f"Changing title for {self.sheet_path_h}: `{old_title_ori}` -> "
+                     f"`{self.title_ori}` [expanded `{self.title}`]")
+        if olds is None:
+            olds = {}
+        olds[self.sheet_path] = (old_title, old_title_ori)
+        for sch in self.sheets:
+            sch.sch.set_titles(title, olds)
+        return olds
+
+    def restore_titles(self, olds):
+        cur_title_ori = self.title_ori
+        old_values = olds[self.sheet_path]
+        self.title_ori = old_values[1]
+        self.title = old_values[0]
+        logger.debug(f"Restoring title for {self.sheet_path_h}: `{cur_title_ori}` -> "
+                     f"`{self.title_ori}` [expanded `{self.title}`]")
+        for sch in self.sheets:
+            sch.sch.restore_titles(olds)
+
     def get_full_path(self, ori=True):
         """ Path using the UUID of the root. Used by v7 """
         path = '/'+self.root_sheet.uuid
diff --git a/kibot/out_any_sch_print.py b/kibot/out_any_sch_print.py
@@ -120,6 +120,8 @@ def __init__(self):
             self.title = ''
             """ Text used to replace the sheet title. %VALUE expansions are allowed.
                 If it starts with `+` the text is concatenated """
+            self.title_propagate = False
+            """ When enabled we also set the title for all the sub-sheets """
             self.sheet_reference_layout = ''
             """ Worksheet file (.kicad_wks) to use. Leave empty to use the one specified in the project.
                 This option works only when you print the toplevel sheet of a project and the project
@@ -199,7 +201,7 @@ def run(self, name):
         replaced_images = self.sch_replace_images(GS.sch)
         try:
             if self.title:
-                self.set_title(self.title, sch=True)
+                self.set_title(self.title, sch=True, propagate=self.title_propagate)
             sch_file = self.save_tmp_sch_if_variant(force=self.title or replaced_images)
             fmt = 'hpgl' if self._expand_ext == 'plt' else self._expand_ext
             cmd = [command, 'export', '--file_format', fmt, '-o', name]
diff --git a/kibot/out_base.py b/kibot/out_base.py
@@ -938,7 +938,7 @@ def unfilter_pcb_components(self, do_3D=False, do_2D=True):
         if self._sub_pcb:
             self._sub_pcb.revert(self._comps_hash)
 
-    def set_title(self, title, sch=False):
+    def set_title(self, title, sch=False, propagate=False):
         self.old_title = None
         if title:
             if sch:
@@ -950,14 +950,17 @@ def set_title(self, title, sch=False):
             if text[0] == '+':
                 text = self.old_title+text[1:]
             if sch:
-                self.old_title = GS.sch.set_title(text)
+                self.old_title = GS.sch.set_titles(text) if propagate else GS.sch.set_title(text)
             else:
                 tb.SetTitle(text)
 
     def restore_title(self, sch=False):
         if self.old_title is not None:
             if sch:
-                GS.sch.set_title(self.old_title)
+                if isinstance(self.old_title, str):
+                    GS.sch.set_title(self.old_title)
+                else:
+                    GS.sch.restore_titles(self.old_title)
             else:
                 GS.board.GetTitleBlock().SetTitle(self.old_title)
             self.old_title = None
diff --git a/tests/GUI/outputs b/tests/GUI/outputs
@@ -3426,6 +3426,13 @@
           ],
           null
         ],
+        [
+          "title_propagate",
+          [
+            "DataTypeBoolean"
+          ],
+          null
+        ],
         [
           "sheet_reference_layout",
           [
@@ -5280,6 +5287,13 @@
           ],
           null
         ],
+        [
+          "title_propagate",
+          [
+            "DataTypeBoolean"
+          ],
+          null
+        ],
         [
           "sheet_reference_layout",
           [
@@ -12469,6 +12483,13 @@
           ],
           null
         ],
+        [
+          "title_propagate",
+          [
+            "DataTypeBoolean"
+          ],
+          null
+        ],
         [
           "sheet_reference_layout",
           [
@@ -13523,6 +13544,13 @@
           ],
           null
         ],
+        [
+          "title_propagate",
+          [
+            "DataTypeBoolean"
+          ],
+          null
+        ],
         [
           "sheet_reference_layout",
           [
@@ -15937,6 +15965,13 @@
           ],
           null
         ],
+        [
+          "title_propagate",
+          [
+            "DataTypeBoolean"
+          ],
+          null
+        ],
         [
           "sheet_reference_layout",
           [
diff --git a/tests/GUI/stats b/tests/GUI/stats
