From 383c41cdc6441510bcbab00f5de80ffe6a0cbba4 Mon Sep 17 00:00:00 2001 From: Gaute Svanes Lunde Date: Fri, 6 Jan 2023 15:46:16 +0100 Subject: [PATCH] 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 --- docs/_extensions/external_content.py | 28 ++++++++++++------- docs/conf.py | 1 + docs/guides/matter-repl.md | 4 +-- .../light-switch-app/nrfconnect/README.md | 6 ++-- examples/shell/mbed/README.md | 2 +- examples/shell/openiotsdk/README.md | 4 +-- 6 files changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/_extensions/external_content.py b/docs/_extensions/external_content.py index 1f4aa27d36910d..f8c2f48a2207ba 100644 --- a/docs/_extensions/external_content.py +++ b/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, ) diff --git a/docs/conf.py b/docs/conf.py index 5c7ed52894a9b4..3625b2bca32e60 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -73,5 +73,6 @@ "scripts/", "examples/android/", "examples/platform/", + "platform", ] external_content_link_extensions = [".md", ".png", ".jpg", ".svg"] diff --git a/docs/guides/matter-repl.md b/docs/guides/matter-repl.md index f5c9214d2c652b..bf05be63ddb9a5 100644 --- a/docs/guides/matter-repl.md +++ b/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 diff --git a/examples/light-switch-app/nrfconnect/README.md b/examples/light-switch-app/nrfconnect/README.md index 68060c9542f880..4c3f7bcfa21b6d 100644 --- a/examples/light-switch-app/nrfconnect/README.md +++ b/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 diff --git a/examples/shell/mbed/README.md b/examples/shell/mbed/README.md index 74d648b9925e99..16a9f987bc5c8f 100644 --- a/examples/shell/mbed/README.md +++ b/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) diff --git a/examples/shell/openiotsdk/README.md b/examples/shell/openiotsdk/README.md index 5307edf1f86cd2..3acf66098b0094 100644 --- a/examples/shell/openiotsdk/README.md +++ b/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: