stable links: added docu and an end2end test for the copy button

Author: thseiler

docs/_assets/Feature_Copy_Stable_Link.png

@@ -2130,6 +2130,34 @@ The options ``--formats=html`` and ``--output-dir output-html`` can be skipped b
 StrictDoc does not detect .sdoc files in the output folder. This is based on the assumption that StrictDoc should not read anything in the output folder, which is intended for transient output artifacts.
 <<<
 
+[SECTION]
+MID: dcc6a2bc11424cf2b114b25a7f65530d
+UID: SECTION-UG-Inbound-Links
+TITLE: Inbound Links
+
+[TEXT]
+MID: 742831d32ca54791b53c1dbbbd070b55
+STATEMENT: >>>
+To enable integration of StrictDoc with external tools such as bug trackers, project management systems, or wikis, StrictDoc supports stable inbound links to any node that has a ``UID``.
+
+To create a stable link, click the "Copy Stable Link" button located in the top-left corner of a requirement or section block:
+
+.. image:: _assets/Feature_Copy_Stable_Link.png
+   :alt: copy a stable link
+   :class: image
+   :width: 400
+
+The stable links have the form of a URL pointing to the project's main index page, followed by the UID (or MID) as an anchor. For example:
+
+``http://your-strictdoc-site/#SDOC_UG_HELLO_WORLD``
+
+``http://your-strictdoc-site/#742831d32ca54791b53c1dbbbd070b55``
+
+When such a link is opened, StrictDoc automatically resolves the UID (or MID) and forwards the user to the appropriate page and position within the project. This allows requirements to be moved between sections or files without breaking external references.
+<<<
+
+[/SECTION]
+
 [SECTION]
 MID: 1b41e7c036cf4e3282fa3d4e687bf95d
 TITLE: Standalone HTML pages

docs/strictdoc_01_user_guide.sdoc

@@ -0,0 +1,16 @@
+[GRAMMAR]
+ELEMENTS:
+- TAG: REQUIREMENT
+  FIELDS:
+  - TITLE: MID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: UID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: TITLE
+    TYPE: String
+    REQUIRED: False
+  - TITLE: STATEMENT
+    TYPE: String
+    REQUIRED: False

tests/end2end/screens/document/copy_stable_link/input/grammar.sgra

@@ -0,0 +1,70 @@
+[DOCUMENT]
+MID: 6a8bc1d467c348dbad29707cd6a3f260
+TITLE: Stable URI Test
+OPTIONS:
+  ENABLE_MID: True
+  MARKUP: HTML
+
+[GRAMMAR]
+IMPORT_FROM_FILE: grammar.sgra
+
+[REQUIREMENT]
+MID: 7726fa20788c493ca8d02bccd2480a9c
+UID: ROOT-1
+TITLE: Requirement in root
+STATEMENT: <input id="copy_stable_link_form_field">
+
+[SECTION]
+MID: 15fa7f4bd56a41eb9da62584961d73b4
+TITLE: Section without UID containing a requirement
+
+[REQUIREMENT]
+MID: 753286690619492fa9c3ae4f9bf5368d
+UID: REQ-WITHIN-SECTION-THAT-HAS-NO-UID
+TITLE: Requirment within a Section
+STATEMENT: lorem ipsum
+
+[/SECTION]
+
+[SECTION]
+MID: 82e3eec5e08146bd8fe213f5a1d8a355
+UID: SECTION-1
+TITLE: Section that has an UID
+
+[TEXT]
+STATEMENT: lorem ipsum
+
+[/SECTION]
+
+[SECTION]
+MID: 0915d681276c4f44a1e1930434edc5cf
+UID: SECTION-2
+TITLE: Section with UID containing a requirement
+
+[REQUIREMENT]
+MID: 63414e7641a8445b962c3c1edc91bf0f
+UID: REQ-WITHIN-SECTION-2
+TITLE: Requirement within a Section that has a UID
+STATEMENT: lorem ipsum
+
+[/SECTION]
+
+[SECTION]
+MID: 0dd59cda6a3a4ec784d7dc2b5791b92f
+UID: SECTION-3
+TITLE: Nested Sections Test
+
+[SECTION]
+MID: 9978c6da28744db89acbe5875caf5a5c
+UID: SECTION-3-1
+TITLE: Subsection for the nexted section test
+
+[REQUIREMENT]
+MID: 3e06d65b527d4cab87680232880a3430
+UID: REQ-WITHIN-SECTION-3-1
+TITLE: Requirement within a nested Section
+STATEMENT: lorem ipsum
+
+[/SECTION]
+
+[/SECTION]

tests/end2end/screens/document/copy_stable_link/input/index.sdoc

@@ -0,0 +1,68 @@
+import os
+import platform
+
+from selenium.webdriver.common.action_chains import ActionChains
+from selenium.webdriver.common.keys import Keys
+
+from tests.end2end.e2e_case import E2ECase
+from tests.end2end.exporter import SDocTestHTMLExporter
+from tests.end2end.helpers.screens.document.screen_document import (
+    Screen_Document,
+)
+
+MODIFIER_KEY = Keys.COMMAND if platform.system() == "Darwin" else Keys.CONTROL
+
+path_to_this_test_file_folder = os.path.dirname(os.path.abspath(__file__))
+
+
+class Test(E2ECase):
+    def test_copy_stable_link(self):
+        with SDocTestHTMLExporter(
+            input_path=path_to_this_test_file_folder
+        ) as exporter:
+            target = "ROOT-1"
+
+            # open the project index with the target UID reference
+            self.open(
+                exporter.get_output_path_as_uri()
+                + "copy_stable_link/input/index.html#"
+                + target
+            )
+
+            screen_document = Screen_Document(self)
+            screen_document.assert_on_screen("document")
+
+            # move mouse to hover over target, so that button becomes visible
+            screen_document.test_case.hover_on_element(
+                f'//sdoc-field-content[sdoc-autogen[text()="{target}"]]'
+            )
+
+            # now click on the target's copy_stable_link button
+            screen_document.test_case.click_xpath(
+                f'//div[@class="copy_stable_link-button" and @data-path="../../#{target}"]'
+            )
+
+            # focus on the input field
+            screen_document.test_case.click_xpath(
+                '//input[@id="copy_stable_link_form_field"]'
+            )
+
+            # Send Ctrl+V to paste clipboard content into input field
+            actions = ActionChains(screen_document.test_case.driver)
+            actions.key_down(MODIFIER_KEY).send_keys("v").key_up(
+                MODIFIER_KEY
+            ).perform()
+
+            # read the content of the input field
+            input_field = screen_document.test_case.find_element(
+                '//input[@id="copy_stable_link_form_field"]'
+            )
+
+            # Get the text from the input field
+            value = input_field.get_attribute("value")
+
+            # check if stable link is as expected
+            assert (
+                value
+                == exporter.get_output_path_as_uri() + "index.html#" + target
+            )