From 40b2e14969bb1219a0b75f3b16d90df341e5496a Mon Sep 17 00:00:00 2001 From: Fabien Lelaquais Date: Fri, 9 Jun 2023 09:28:06 +0200 Subject: [PATCH] - Visual Elements controls and blocks pages restored. - Elements documentation build process simplification. --- docs/manuals/gui/binding.md | 2 +- .../gui/{ => viselements}/blocks.md_template | 0 .../{ => viselements}/controls.md_template | 0 docs/manuals/gui/viselements/index.md | 4 +- docs/manuals/gui/viselements/text.md_template | 2 +- mkdocs.yml_template | 4 +- tools/_setup_generation/elmnts_generator.py | 31 ++++++--------- tools/_setup_generation/step_corelements.py | 23 ++++------- tools/_setup_generation/step_viselements.py | 38 ++++++++----------- 9 files changed, 41 insertions(+), 63 deletions(-) rename docs/manuals/gui/{ => viselements}/blocks.md_template (100%) rename docs/manuals/gui/{ => viselements}/controls.md_template (100%) diff --git a/docs/manuals/gui/binding.md b/docs/manuals/gui/binding.md index 8fd05dd35..d6adb3b69 100644 --- a/docs/manuals/gui/binding.md +++ b/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. diff --git a/docs/manuals/gui/blocks.md_template b/docs/manuals/gui/viselements/blocks.md_template similarity index 100% rename from docs/manuals/gui/blocks.md_template rename to docs/manuals/gui/viselements/blocks.md_template diff --git a/docs/manuals/gui/controls.md_template b/docs/manuals/gui/viselements/controls.md_template similarity index 100% rename from docs/manuals/gui/controls.md_template rename to docs/manuals/gui/viselements/controls.md_template diff --git a/docs/manuals/gui/viselements/index.md b/docs/manuals/gui/viselements/index.md index 6bac2526b..0ae11caba 100644 --- a/docs/manuals/gui/viselements/index.md +++ b/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 diff --git a/docs/manuals/gui/viselements/text.md_template b/docs/manuals/gui/viselements/text.md_template index 4be79da5d..701ab856b 100644 --- a/docs/manuals/gui/viselements/text.md_template +++ b/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 diff --git a/mkdocs.yml_template b/mkdocs.yml_template index cfe006f08..fc11c12cb 100644 --- a/mkdocs.yml_template +++ b/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 diff --git a/tools/_setup_generation/elmnts_generator.py b/tools/_setup_generation/elmnts_generator.py index 03cea1a83..23551dd8f 100644 --- a/tools/_setup_generation/elmnts_generator.py +++ b/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'\n' + f'\n' + f"
{e}
\n" - + f'\n' - + f'\n' - + f'\n' - + f'\n' + + f'\n' + + f'\n' + + f'\n' + + f'\n' + f"

{first_documentation_paragraph}

\n" + "\n" ) @@ -218,10 +211,10 @@ def generate_element_doc(element_type: str, element_desc: Dict): # The toc header and footer must then be "" and "" 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 = '
\n' for element_type in self.categories[category]: toc += generate_element_doc(element_type, self.elements[element_type]) diff --git a/tools/_setup_generation/step_corelements.py b/tools/_setup_generation/step_corelements.py index ebc857bb6..7963e5cbb 100644 --- a/tools/_setup_generation/step_corelements.py +++ b/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) diff --git a/tools/_setup_generation/step_viselements.py b/tools/_setup_generation/step_viselements.py index e2458d0a0..a44c69a5b 100644 --- a/tools/_setup_generation/step_viselements.py +++ b/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