- Visual Elements controls and blocks pages restored.

- Elements documentation build process simplification.

docs/manuals/gui/binding.md

@@ -70,7 +70,7 @@ where the page is defined, then the main module.
 
 !!! important "Defining a page scope"
     A page scope, where variables used in a page definition are searched, is the module
-    where the page *instance* (an instance of the `Markdown^` or the `HTML^` classes),
+    where the page *instance* (an instance of the `Markdown^` or the `Html^` classes),
     **not** the text of the page.
 
 This mechanism allows pages to bind to local variables declared on their own module.

docs/manuals/gui/viselements/index.md

@@ -17,11 +17,11 @@ There are two types of _Visual Elements_:
 If you are familiar with what _Visual Elements_ are and how they are declared, you
 may want to jump directly to the list of the available visual elements:
 
-[:material-arrow-right: List of available controls](../controls.md)
+[:material-arrow-right: List of available controls](controls.md)
 
 [:material-arrow-right: List of available Core back-end controls](../corelements)
 
-[:material-arrow-right: List of available blocks](../blocks.md)
+[:material-arrow-right: List of available blocks](blocks.md)
 
 ## Properties
 

docs/manuals/gui/viselements/text.md_template

@@ -1,7 +1,7 @@
 Displays a value as a static text.
 
 Note that in order to create a `text` control, you don't need to specify the control name
-in the text template. See the documentation for [Controls](../controls.md) for more details.
+in the text template. See the documentation for [Controls](controls.md) for more details.
 
 ## Details
 

mkdocs.yml_template

@@ -20,10 +20,10 @@ nav:
         - "Pages": manuals/gui/pages.md
         - "Visual Elements":
            - manuals/gui/viselements/index.md
-           - "Controls": manuals/gui/controls.md
+           - "Controls": manuals/gui/viselements/controls.md
            - "Core Back-end Controls":
               - manuals/gui/corelements/index.md
-           - "Blocks": manuals/gui/blocks.md
+           - "Blocks": manuals/gui/viselements/blocks.md
         - "Binding variables": manuals/gui/binding.md
         - "Callbacks": manuals/gui/callbacks.md
         - "Notifications": manuals/gui/notifications.md

tools/_setup_generation/elmnts_generator.py

@@ -10,9 +10,6 @@ class ElementsGenerator(SetupStep):
     NAME = "name"
     INHERITS = "inherits"
 
-    def get_doc_dir(self) -> str:
-        raise NotImplemented("ElementsGenerator get_doc_dir() must be defined.")
-
     # Load elements, test validity of doc and resolve inheritance
     def load_elements(self, elements_json_path: str, categories: List[str]) -> None:
         with open(elements_json_path) as elements_json_file:
@@ -84,10 +81,10 @@ def merge(element_desc, parent_element_desc, default_property) -> Optional[str]:
                 raise ValueError(
                     f"FATAL - No properties for element type '{element}'"
                 )
-            doc_path = self.get_element_template_path(element)
-            if not os.access(doc_path, os.R_OK):
+            template_path = self.get_element_md_path(element) + "_template"
+            if not os.access(template_path, os.R_OK):
                 raise FileNotFoundError(
-                    f"FATAL - Could not find doc for element type '{element}' at {doc_path}"
+                    f"FATAL - Could not find doc for element type '{element}' at {template_path}"
                 )
             # Check completeness
             for property in element_desc[__class__.PROPERTIES]:
@@ -102,9 +99,6 @@ def merge(element_desc, parent_element_desc, default_property) -> Optional[str]:
     # Find first level 2 or 3 header
     FIRST_HEADER2_RE = re.compile(r"(^.*?)(\n###?\s+)", re.MULTILINE | re.DOTALL)
 
-    def get_element_template_path(self, element_type: str) -> str:
-        raise NotImplementedError(f"get_element_template_path() not implemented (element was {element_type}).")
-
     def get_element_md_path(self, element_type: str) -> str:
         raise NotImplementedError(f"get_element_md_path() not implemented (element was {element_type}).")
 
@@ -115,13 +109,13 @@ def element_page_hook(self, element_type:str, doc:str, before_properties: str, a
         return (None, None)
 
     # Generate element doc pages for that category
-    def generate_pages(self, category: str, md_path: str, md_template_path: str) -> None:
+    def generate_pages(self, category: str, md_path: str) -> None:
         def generate_element_doc(element_type: str, element_desc: Dict):
             """
             Returns the entry for the Table of Contents that is inserted
             in the global Visual Elements or Core Elements doc page.
             """
-            template_doc_path = self.get_element_template_path(element_type) 
+            template_doc_path = self.get_element_md_path(element_type) + "_template"
             with open(template_doc_path, "r") as template_doc_file:
                 element_documentation = template_doc_file.read()
             # Retrieve first paragraph from element documentation
@@ -202,14 +196,13 @@ def generate_element_doc(element_type: str, element_desc: Dict):
                     + after_properties
                 )
             e = element_type  # Shortcut
-            d = self.get_doc_dir()
             return (
-                f'<a class="tp-ve-card" href="../{d}/{e}/">\n'
+                f'<a class="tp-ve-card" href="../{e}/">\n'
                 + f"<div>{e}</div>\n"
-                + f'<img class="tp-ve-l" src="../{d}/{e}-l.png"/>\n'
-                + f'<img class="tp-ve-lh" src="../{d}/{e}-lh.png"/>\n'
-                + f'<img class="tp-ve-d" src="../{d}/{e}-d.png"/>\n'
-                + f'<img class="tp-ve-dh" src="../{d}/{e}-dh.png"/>\n'
+                + f'<img class="tp-ve-l" src="../{e}-l.png"/>\n'
+                + f'<img class="tp-ve-lh" src="../{e}-lh.png"/>\n'
+                + f'<img class="tp-ve-d" src="../{e}-d.png"/>\n'
+                + f'<img class="tp-ve-dh" src="../{e}-dh.png"/>\n'
                 + f"<p>{first_documentation_paragraph}</p>\n"
                 + "</a>\n"
             )
@@ -218,10 +211,10 @@ def generate_element_doc(element_type: str, element_desc: Dict):
             # The toc header and footer must then be "<ui>" and "</ul>" respectively.
 
         md_template = ""
-        with open(md_template_path) as template_file:
+        with open(f"{md_path}_template") as template_file:
             md_template = template_file.read()
         if not md_template:
-            raise FileNotFoundError(f"FATAL - Could not read {md_template_path} markdown template")
+            raise FileNotFoundError(f"FATAL - Could not read {md_path}_template markdown template")
         toc = '<div class="tp-ve-cards">\n'
         for element_type in self.categories[category]:
             toc += generate_element_doc(element_type, self.elements[element_type])

tools/_setup_generation/step_corelements.py

@@ -5,12 +5,11 @@
 # document pages.
 #
 # For each element, this script combines its property list and
-# documentation (located in [CORELEMENTS_SRC_PATH]), and generates full
-# Markdown files in [CORELEMENTS_DIR_PATH]. All these files ultimately get
-# integrated in the global dos set.
+# documentation, and generates full arkdown files in [CORELEMENTS_DIR_PATH]. All
+# these files ultimately get integrated in the global doc set.
 #
-# The template documentation files [CORELEMENTS_SRC_PATH]/[controls|blocks].md_template
-# are also completed with generated table of contents.
+# The template documentation file [CORELEMENTS_DIR_PATH]/index.md_template
+# is also completed with generated table of contents.
 # ################################################################################
 from .setup import Setup
 from .elmnts_generator import ElementsGenerator
@@ -24,24 +23,18 @@ def get_id(self) -> str:
     def get_description(self) -> str:
         return "Extraction of the Core elements documentation"
 
-    def get_doc_dir(self) -> str:
-        return "corelements"
-
     def enter(self, setup: Setup):
         self.CORELEMENTS_DIR_PATH = setup.manuals_dir + "/gui/corelements"
-        self.template_path = self.CORELEMENTS_DIR_PATH + "/index.md_template"
-        if not os.access(self.template_path, os.R_OK):
+        self.index_path = self.CORELEMENTS_DIR_PATH + "/index.md"
+        if not os.access(f"{self.index_path}_template", os.R_OK):
             raise FileNotFoundError(
-                f"FATAL - Could not read {self.template_path} markdown template"
+                f"FATAL - Could not read {self.index_path}_template markdown template"
             )
         self.load_elements(setup.root_dir + "/taipy/gui_core/viselements.json",
                            ["controls"])
 
-    def get_element_template_path(self, element_type: str) -> str:
-        return f"{self.CORELEMENTS_DIR_PATH}/{element_type}.md_template"
-
     def get_element_md_path(self, element_type: str) -> str:
         return f"{self.CORELEMENTS_DIR_PATH}/{element_type}.md"
 
     def setup(self, setup: Setup) -> None:
-        self.generate_pages("controls", os.path.join(self.CORELEMENTS_DIR_PATH, "index.md"), self.template_path)
+        self.generate_pages("controls", self.index_path)

tools/_setup_generation/step_viselements.py

@@ -5,11 +5,11 @@
 # and the blocks document pages.
 #
 # For each visual element, this script combines its property list and core
-# documentation (located in [VISELEMENTS_SRC_PATH]), and generates full
-# Markdown files in [VISELEMENTS_DIR_PATH]. All these files ultimately get
-# integrated in the global dos set.
+# documentation, and generates full Markdown files in [VISELEMENTS_DIR_PATH]. All
+# these files ultimately get integrated in the global doc set.
 #
-# The skeleton documentation files [GUI_DOC_PATH]/[controls|blocks].md_template
+# The skeleton documentation files
+# [VISELEMENTS_DIR_PATH]/[controls|blocks].md_template
 # are also completed with generated table of contents.
 # ################################################################################
 from .setup import Setup
@@ -25,21 +25,19 @@ def get_id(self) -> str:
     def get_description(self) -> str:
         return "Extraction of the visual elements documentation"
 
-    def get_doc_dir(self) -> str:
-        return "viselements"
-
     def enter(self, setup: Setup):
-        self.GUI_DIR_PATH = setup.manuals_dir + "/gui"
-        self.VISELEMENTS_DIR_PATH = self.GUI_DIR_PATH + "/viselements"
-        self.controls_template_path = self.GUI_DIR_PATH + "/controls.md_template"
-        if not os.access(self.controls_template_path, os.R_OK):
+        self.VISELEMENTS_DIR_PATH = setup.manuals_dir + "/gui/viselements"
+        self.controls_path = self.get_element_md_path("controls")
+        template_path = f"{self.controls_path}_template"
+        if not os.access(template_path, os.R_OK):
             raise FileNotFoundError(
-                f"FATAL - Could not read {self.controls_template_path} Markdown template"
+                f"FATAL - Could not read {template_path} Markdown template"
             )
-        self.blocks_template_path = self.GUI_DIR_PATH + "/blocks.md_template"
-        if not os.access(self.blocks_template_path, os.R_OK):
+        self.blocks_path = self.get_element_md_path("blocks")
+        template_path = f"{self.blocks_path}_template"
+        if not os.access(template_path, os.R_OK):
             raise FileNotFoundError(
-                f"FATAL - Could not read {self.blocks_template_path} Markdown template"
+                f"FATAL - Could not read {template_path} Markdown template"
             )
         self.charts_home_html_path = self.VISELEMENTS_DIR_PATH + "/charts/home.html_fragment"
         if not os.access(self.charts_home_html_path, os.R_OK):
@@ -50,18 +48,12 @@ def enter(self, setup: Setup):
                            ["controls", "blocks"])
 
 
-    def get_element_template_path(self, element_type: str) -> str:
-        return f"{self.VISELEMENTS_DIR_PATH}/{element_type}.md_template"
-
     def get_element_md_path(self, element_type: str) -> str:
         return f"{self.VISELEMENTS_DIR_PATH}/{element_type}.md"
 
     def setup(self, setup: Setup) -> None:
-        # Create VISELEMS_DIR_PATH directory if necessary
-        if not os.path.exists(self.VISELEMENTS_DIR_PATH):
-            os.mkdir(self.VISELEMENTS_DIR_PATH)
-        self.generate_pages("controls", self.get_element_md_path("controls"), self.controls_template_path)
-        self.generate_pages("blocks",   self.get_element_md_path("blocks"), self.blocks_template_path)
+        self.generate_pages("controls", self.controls_path)
+        self.generate_pages("blocks",   self.get_element_md_path("blocks"))
 
     def element_page_hook(self, element_type:str, element_documentation: str, before: str, after: str) -> tuple[str, str]:
         # Special case for charts: we want to insert the chart gallery that is stored in the