Merge pull request #6 from ZeissIQS/2022

2022

doc/_static/css/theme_zeiss.css

@@ -0,0 +1,171 @@
+/****************************************************************************** 
+ * Override some styles to match ZEISS branding
+ *
+ * See https://brand.zeiss.com/
+ *
+ * Copyright 2023, Carl Zeiss GOM Metrology GmbH
+ ******************************************************************************/
+
+/* Based on Read the Docs theme */
+@import 'theme.css';
+
+
+/******************************************************************************
+ * Fonts
+ ******************************************************************************/
+
+/* Use font "ZEISS Frutiger Next W1G" */
+@font-face {
+	font-family: "Frutiger Next";
+	src: url("../fonts/ZEISS-Frutiger-Next-W02-Regular.woff2") format("woff2"),
+	url("../fonts/ZEISS-Frutiger-Next-W02-Regular-Italic.woff2") format("woff2"),
+    url("../fonts/ZEISS-Frutiger-Next-W02-Medium.woff2") format("woff2"),
+	url("../fonts/ZEISS-Frutiger-Next-W02-Bold.woff2") format("woff2");
+}
+
+:root {
+    --font-family-frutiger: "Frutiger Next", "Helvetica Neue", Helvetica, Verdana, Arial, sans-serif;
+}
+
+html, body, .rst-content .toctree-wrapper>p.caption, h1, h2, h3, h4, h5, h6, legend {
+    font-family: var(--font-family-frutiger);
+    color: #000000; /* was #404040 */
+}
+
+
+/******************************************************************************
+ * Links
+ ******************************************************************************/
+
+/* Changed from #2980b9 -> ZEISS Azure */
+a {
+    color: #0072EF;
+}
+
+/* Changed from #9b59b6 -> ZEISS Saphire */
+a:visited {
+    color: #4C6BB1;
+}
+
+
+/******************************************************************************
+ * Menu section text, changed from #55a5d9 -> ZEISS Sky Blue, from 85% -> 100%
+ ******************************************************************************/
+
+/* Menu section text, changed from #55a5d9 -> ZEISS Sky Blue, from 85% -> 100% */
+.wy-menu-vertical p.caption {
+    color: #6AB0E2;
+    font-size: 100%;
+}
+
+/* Menu text, changed from #404040 to ZEISS Black */
+.wy-menu-vertical li.toctree-l2 a, .wy-menu-vertical li.toctree-l3 a, .wy-menu-vertical li.toctree-l4 a, .wy-menu-vertical li.toctree-l5 a, .wy-menu-vertical li.toctree-l6 a, .wy-menu-vertical li.toctree-l7 a, .wy-menu-vertical li.toctree-l8 a, .wy-menu-vertical li.toctree-l9 a, .wy-menu-vertical li.toctree-l10 a {
+    color: #000000;
+}
+
+/* Menu text, changed from #404040 -> ZEISS Black*/
+.wy-menu-vertical li.current>a, .wy-menu-vertical li.on a {
+    color: #000000;
+}
+
+/* Changed from #298069 -> ZEISS Ultradark Gray */ 
+.wy-side-nav-search {
+    background: #32373E;
+}
+
+/* Changed from #343131 -> ZEISS Ultradark Gray */
+.wy-nav-side {
+    background: #32373E;
+}
+
+/* Menu level 1, changed from #d9d9d9 -> ZEISS White */
+.wy-menu-vertical a {
+    color: #FFFFFF;
+}
+
+/* Menu level 1, changed from #fcfcfc -> ZEISS Light Gray */
+.wy-menu-vertical li.current>a {
+    background: #B4C0CA;
+}
+
+/* Menu level 2, changed from c9c9c9 -> ZEISS Ultralight Gray */
+.wy-menu-vertical li.toctree-l2.current>a {
+    background: #DCE3E9;
+}
+
+/* Menu level 3, changed from #c9c9c9 -> ZEISS Semiwhite Gray */
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a {
+    background: #F2F5F8;
+}
+
+
+/* Changed from #d6d6d6/#c9c9c9 -> ZEISS Azure */
+.wy-menu-vertical li.current a:hover, .wy-menu-vertical li.toctree-l2.current li.toctree-l3>a:hover {
+    background: #0072EF;
+}
+
+/* Changed from #fcfcfc */
+.wy-nav-content-wrap, .wy-body-for-nav, .wy-nav-content, .wy-dropdown-menu {
+    background: #ffffff;
+}
+
+
+/******************************************************************************
+ * Admonitions
+ ******************************************************************************/
+
+/* Changed from #6ab0de -> ZEISS Saphire */
+.rst-content .note .admonition-title, .rst-content .seealso .admonition-title {
+    background: #4C6BB1;
+}
+
+/* Changed from #e7f2fa -> ZEISS Ultralight Gray */
+.rst-content .note, .rst-content .seealso {
+    background: #DCE3E9;
+}
+
+/* Changed from #1abc9c -> ZEISS Green */
+.rst-content .important .admonition-title, .rst-content .hint .admonition-title, .rst-content .caution .admonition-title {
+    background: #1E8565;
+}
+
+/* Changed from #dbfaf4 -> ZEISS Ultralight Gray */
+.rst-content .important, .rst-content .hint, .rst-content .caution {
+    background: #DCE3E9;
+}
+
+/* Changed from #f0b37e -> ZEISS Bright Orange Neon */
+.rst-content .warning .admonition-title, .rst-content .attention .admonition-title {
+    background: #E71E1E;
+}
+
+/* Changed from # #ffedcc -> ZEISS Ultralight Gray */
+.rst-content .warning, .rst-content .attention {
+    background: #DCE3E9;
+}
+
+
+/******************************************************************************
+ * Literal text / code examples
+ ******************************************************************************/
+
+/* Changed from #e74c3c -> ZEISS Purple Red */
+.rst-content code.literal {
+    color: #A70240;
+}
+
+/* Changed from #f8f8f8 -> ZEISS Semiwhite Gray */
+pre {
+    background: #F2F5F8;
+}
+
+/* Changed from #3D7B7B (increased contrast) */
+.highlight .c1 {
+    color: #2D6B6B;
+}
+
+/* Changed from #AA22FF (increased contrast) */
+.highlight .ow {
+    color: #9A12EF;
+    font-weight: bold;
+}

doc/conf.py

@@ -7,13 +7,13 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'Add-On Documentation'
-copyright = '2022, Carl Zeiss GOM Metrology GmbH'
+copyright = '2023, Carl Zeiss GOM Metrology GmbH'
 author = 'Carl Zeiss GOM Metrology GmbH'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['myst_parser', 'sphinx_rtd_theme', 'sphinx_favicon', 'sphinx.ext.githubpages']
+extensions = ['myst_parser', 'sphinx_rtd_theme', 'sphinx_favicon', 'sphinx.ext.githubpages', 'sphinx_sitemap']
 source_suffix = ['.rst', '.md']
 
 templates_path = ['_templates']
@@ -29,13 +29,25 @@
 
 myst_heading_anchors = 4
 
+# -- Options for sitemap -----------------------------------------------------
+# https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html
+html_baseurl = 'https://zeissiqs.github.io/gom-software-python-api/2022/'
+sitemap_url_scheme = "{link}"
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 #html_theme = 'alabaster'
 html_theme = "sphinx_rtd_theme"
+# "Read the docs" appends " &mdash; <project>  documentation" to the page heading -
+# this changes the title to "<page_heading> &mdash; <project>"
+html_title = project
 html_static_path = ['_static']
 
+# -- Override some "sphinx_rtd_theme" styles to match ZEISS branding ---------------
+# https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html
+html_style = "css/theme_zeiss.css"
+
 favicons = [
     {
         "rel": "icon",
@@ -44,3 +56,6 @@
         "type": "image/png",
     }
 ]
+
+# Source: https://brand.zeiss.com/cmsPublic/brandportal/basic-design-elements/logo-tagline.html
+html_logo =  "_static/zeiss-logo-rgb.png"

doc/howtos/localization/localization.md

@@ -0,0 +1,145 @@
+# Localization of packages
+
+## Writing translatable scripts
+
+### User-defined script dialogs
+
+When adding a user defined script dialog to a script, since software version 2022 the resulting code is in JSON compatible format and will contain translation entries for all translatable texts automatically. The user does not have to care for these entries manually. They are kept consistently when the dialog is edited again and will lead to translation file entries (see below).
+
+``` Python
+DIALOG=gom.script.sys.create_user_defined_dialog (dialog={
+    "content": [
+        [
+            {
+                "columns": 1,
+                "monospace": False,
+                "name": "log",
+                "rows": 1,
+                "save_dialog_title": {
+                    "id": "",
+                    "text": "Save Log File",
+                    "translatable": True
+                },
+                "scroll_automatically": True,
+                "show_save": False,
+                "tooltip": {
+                    "id": "",
+                    "text": "",
+                    "translatable": True
+                },
+    ...
+    )
+```
+
+### Text in scripts
+
+Texts in script have to be tagged as translatable via using the `tr ()`  function. During translation file generation, these texts will be processed and later replaced at runtime with the available translations.
+
+    print (tr ('This text will be translated'))
+
+
+## Translating scripts
+
+### Generating translatable XLIFF files
+
+💡 Scripts are using standard XLIFF files to access translations in different languages.
+
+#### Install package 'Internationalization'
+
+* Install the package 'Internationalization'.
+* Possible via package Manager or via downloading it from the connect directly plus drag/drop onto the application.
+
+#### Switch package into 'Edit' mode
+
+* Select the package the translations should be added to.
+* Switch it into 'Edit' mode:
+
+    ![Switch into edit mode](assets/edit_mode.png)
+
+#### Execute script 'Update XLIFF files'
+
+![Start from menu](assets/start_from_menu.png)
+
+* Execute script 'Update XLIFF files' from package 'Internationalization'.
+* Select the package with the translations which shall be generated or updated (1)
+* Set the comma separated list of language identifiers for which translation files will be generated (2)
+* Check the displayed number of translated texts for plausibility (3)
+* Press 'Update' (4) to generate translatable XLIFF files (4)
+
+    ![Update XLIFF](assets/update_xliff.png)
+
+* Afterwards, the package's XLIFF translatable files will be present in the package's languages folder:
+
+    ![XLIFF files](assets/xliff_files.png)
+
+#### Translate XLIFF files
+
+* Export the XLIFF files via 'Export Resource...' on the right mouse menu.
+* Translate the XLIFF files. This can be done either manually or by importing them into a translation software, possibly via a translation service provider.
+* Import the XLIFF files back into the package via 'Import Resource...' on the right mouse menu.
+
+``` XML
+<ns0:xliff xmlns:ns0="urn:oasis:names:tc:xliff:document:1.1" version="1.1">
+    <file original="DL_ANALYSIS_01_curve_based.py" datatype="py" source-language="en" target-language="de">
+    <group restype="x-gettext-domain" resname="">
+        <trans-unit id="Save Log File">
+        <source xml:space="preserve">Save Log File</source>
+        <target xml:space="preserve">Protokolldatei speichern</target>
+        </trans-unit>
+        <trans-unit id="Curve inspection">
+        <source xml:space="preserve">Curve inspection</source>
+        <target xml:space="preserve">Kurveninspektion</target>
+        </trans-unit>
+        <trans-unit id="Processing...">
+        <source xml:space="preserve">Processing...</source>
+        <target xml:space="preserve">In Bearbeitung...</target>
+        </trans-unit>
+    </group>
+    </file>
+</ns0:xliff>
+```
+
+## Switching package languages
+
+### Enable language
+
+💡 The package language is the same as the globally set application language.
+
+#### Selecting an package/application language
+
+* Select the appropriate language the the applications preferences dialog.
+
+    ![Update XLIFF](assets/language_preferences.png)
+
+* If a matching XLIFF file is present in an package, the translations from this file are used automatically.
+* This might require an application restart due to caching issues.
+
+## FAQ
+
+### Is there a shortcut for exporting/importing the XLIFF files ?
+
+* If there are quite many of these files and the process has to be done regularly, the resource files can be accessed right on file system.
+* Each package in 'Edit' mode mirrors its content into `%APPDATA%/gom/<version>/gom_package_scripts/<package id>`.
+* The XLIFF files can be edited right there of copies/pasted from there as long as the package remains in 'Edit' mode.
+
+### Are the translation entries persistent when updated via the 'Update XLIFF files' script ?
+
+* As long as the original texts (the texts in the 'id' attribute of the 'trans-unit' tag of the XLIFF files) are not changing, already translated entries are left untouched and will persist.
+* This is the case when the original text in the script does not change, like the text in a dialog button or the original text in a scripts 'tr ()' function.
+* Can this scheme be automated, for example in a build queue ?
+* The 'Update XLIFF files' script itself is designed to be interactive.
+* But: The source is available and the logic within can be used as a base to implement a customized XLIFF files updater to automatic execution.
+* The goal of the scheme is to have translated XLIFF files with a name scheme as shown above in the package's 'language' directory.
+
+### After the application language is set, the package is not displaying the translations for that language ?
+
+* You might have to restart the application after switching the application language in the preferences.
+* Please double check, too,  if the package supports that specific language at all.
+
+<!--
+### Are packages built in the internal GOM build system handled the same way ?
+
+* No.
+* Packages built in the internal GOM build system right from version control are subject of a technical documentation team project.
+* See internal documentation for details: [Link]
+-->