doc: move link targets to build folder

Created a change in the `external_content` extension so that
links to content that is also being copied to the _build folder
will point to their new location instead. This enables linking
to sections on other pages.

This change also enables link checking for sections on other
pages, and therefore also includes a fix to some previously
broken section links.

Signed-off-by: Gaute Svanes Lunde <[email protected]>

docs/_extensions/external_content.py

@@ -59,6 +59,7 @@ def adjust_includes(
     encoding: str,
     link_prefixes: List[str],
     extensions: List[str],
+    targets: List[Path],
     dstpath: Optional[Path] = None,
 ) -> None:
     """Adjust included content paths.
@@ -69,6 +70,7 @@ def adjust_includes(
         encoding: Sources encoding.
         link_prefixes: Prefixes of links that are made external.
         extensions: Filename extensions links to which are not made external.
+        targets: List of all files that are being copied.
         dstpath: Destination path for fname if its path is not the actual destination.
     """
 
@@ -81,6 +83,18 @@ def _adjust_path(path):
         # ignore absolute paths, section links, hyperlinks and same folder
         if path.startswith(("/", "#", "http", "www")) or not "/" in path:
             return path
+
+        # for files that are being copied modify reference to and out of /docs
+        filepath = path.split("#")[0]
+        absolute = (basepath / filepath).resolve()
+        if absolute in targets:
+            if "docs/" in path:
+                path = path.replace("docs/", "")
+            elif "../examples" in path:
+                path = path.replace("../", "", 1)
+            return path
+
+        # otherwise change links to point to their targets' original location
         return Path(os.path.relpath(basepath / path, dstpath)).as_posix()
 
     def _adjust_links(m):
@@ -99,12 +113,6 @@ def _adjust_filetype(m):
 
         return f"[{displayed}]({EXTERNAL_LINK_URL_PREFIX}{target})"
 
-    def _remove_section_links(m):
-        (file_link, path) = m.groups()
-        if path.startswith("http"):
-            return m.group(0)
-        return file_link + ")"
-
     def _adjust_image_link(m):
         prefix, fpath, postfix = m.groups()
         fpath_adj = _adjust_path(fpath)
@@ -121,10 +129,6 @@ def _adjust_image_link(m):
             _adjust_external,
         ),
 
-        # Find links that lead to a section within another file and
-        # remove the section part of the link.
-        (r"(\[[^\[\]]*\]\s*\(([^)]*\.md))#.*\)", _remove_section_links),
-
         # Find links that lead to a non-presentable filetype and transform
         # it into an external link.
         (
@@ -183,6 +187,8 @@ def sync_contents(app: Sphinx) -> None:
             else:
                 to_copy.append((src, prefix_src))
 
+    list_of_destinations = [f for f, _ in to_copy]
+
     for entry in to_copy:
         src, prefix_src = entry
         dst = (srcdir / src.relative_to(prefix_src)).resolve()
@@ -202,6 +208,7 @@ def sync_contents(app: Sphinx) -> None:
                 app.config.source_encoding,
                 app.config.external_content_link_prefixes,
                 app.config.external_content_link_extensions,
+                list_of_destinations,
             )
         # if origin file is modified only copy if different
         elif src.stat().st_mtime > dst.stat().st_mtime:
@@ -215,6 +222,7 @@ def sync_contents(app: Sphinx) -> None:
                     app.config.source_encoding,
                     app.config.external_content_link_prefixes,
                     app.config.external_content_link_extensions,
+                    list_of_destinations,
                     dstpath=dst.parent,
                 )
 

docs/conf.py

@@ -73,5 +73,6 @@
     "scripts/",
     "examples/android/",
     "examples/platform/",
+    "platform",
 ]
 external_content_link_extensions = [".md", ".png", ".jpg", ".svg"]

docs/guides/matter-repl.md

@@ -28,8 +28,8 @@ The tool uses the generic CHIP Device Controller library, available in the
 ## Building
 
 Please follow the instructions
-[here](./python_chip_controller_building.md#building) to build the Python
-virtual environment.
+[here](./python_chip_controller_building.md#building-and-installing) to build
+the Python virtual environment.
 
 ## Launching the REPL
 

examples/light-switch-app/nrfconnect/README.md

@@ -671,7 +671,7 @@ example, you can use the
 The ACL should contain information about all clusters that can be called by the
 light switch application. See the section about interacting with ZCL clusters in
 the
-[CHIP Tool's user guide](../../../docs/guides/chip_tool_guide.md#interacting-with-zcl-clusters)
+[CHIP Tool's user guide](../../../docs/guides/chip_tool_guide.md#interacting-with-data-model-clusters)
 for more information about ACLs.
 
 You can perform the binding process to a single remote endpoint (unicast
@@ -689,7 +689,7 @@ same Matter network.
 To perform the unicast binding process, complete the following steps:
 
 1.  Build the CHIP Tool according to the steps from the
-    [CHIP Tool user guide](../../../docs/guides/chip_tool_guide.md#building).
+    [CHIP Tool user guide](../../../docs/guides/chip_tool_guide.md#building-and-running-the-chip-tool).
 2.  Go to the CHIP Tool build directory.
 3.  Add an ACL to the development kit that is programmed with the
     [Lighting Application Example](../../lighting-app/nrfconnect/README.md) by
@@ -741,7 +741,7 @@ same Matter network.
 To perform the unicast binding process, complete the following steps:
 
 1.  Build the CHIP Tool according to the steps from the
-    [CHIP Tool user guide](../../../docs/guides/chip_tool_guide.md#building).
+    [CHIP Tool user guide](../../../docs/guides/chip_tool_guide.md#building-and-running-the-chip-tool).
 2.  Go to the CHIP Tool build directory.
 
 3.  Add the light switch device to the multicast group by running the following

examples/shell/mbed/README.md

@@ -219,4 +219,4 @@ The application supports common Matter shell commands. They are used to control
 the basic functionalities of the device.
 
 For more details visit:
-[Common shell commands](../README.md#chip-shell-command-details)
+[Common shell commands](../README.md#matter-shell-command-details)

examples/shell/openiotsdk/README.md

@@ -6,7 +6,7 @@ execution. There is a set of common shell commands which perform basic device
 operations.
 
 For more details see
-[Common shell commands](../README.md#chip-shell-command-details).
+[Common shell commands](../README.md#matter-shell-command-details).
 
 ## Build and run
 
@@ -34,7 +34,7 @@ supports common Matter shell commands. They are used to control the basic
 functionalities of the device.
 
 For more details read:
-[Common shell commands](../README.md#chip-shell-command-details)
+[Common shell commands](../README.md#matter-shell-command-details)
 
 Example: