From 36eb22720bf1af36473edd7603a15a28ff53813c Mon Sep 17 00:00:00 2001 From: GetPsyched Date: Mon, 4 Nov 2024 15:40:03 +0400 Subject: [PATCH] fix: update docstrings --- .../src/nixos_render_docs/redirects.js | 11 ------ .../src/nixos_render_docs/redirects.py | 38 +++++++++---------- .../src/tests/test_redirects.py | 4 +- 3 files changed, 20 insertions(+), 33 deletions(-) diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/redirects.js b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/redirects.js index 1b59d9be9b1373..38d7734735e916 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/redirects.js +++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/redirects.js @@ -1,14 +1,3 @@ -// the following code matches the current page's anchor against the set of redirects. -// -// it is written to minimize the latency between page load and redirect. -// therefore we avoid function calls, copying data, and unnecessary loops. - -// anchor starts with the hash character (`#`), -// but our redirect declarations don't, so we strip it. -// example: -// document.location.hash -> '#foo' -// document.location.hash.substring(1) -> 'foo' const anchor = document.location.hash.substring(1); - const redirects = REDIRECTS_PLACEHOLDER; if (redirects[anchor]) document.location.href = redirects[anchor]; diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/redirects.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/redirects.py index 81baae7ac8a0bf..0922cad72c2f95 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/redirects.py +++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/redirects.py @@ -17,16 +17,14 @@ class Redirects: def validate(self, xref_targets: dict[str, XrefTarget]): """ - Parse redirects from an static set of identifier-locations pairs - - - Ensure semantic correctness of the set of redirects - - Identifiers not having a redirect entry - - Orphan identifiers not present in source - - Paths redirecting to different locations - - Identifiers conflicting with redirect entries - - Client-side redirects to paths having a server-side redirect (transitivity) - - Flatten redirects into simple key-value pairs for simpler indexing - - Segregate client and server side redirects + Validate redirection mappings against element locations in the output + + - Ensure semantic correctness of the set of redirects with the following rules: + - Identifiers present in the source must have a mapping in the redirects + - Keys of the redirects mapping must correspond to some identifier in the source + - A given historical path must correspond to only one identifier + - Identifiers must not be identical to any historical location's anchor of the same output path + - A client redirect from a path that has a server-side redirect must not exist. """ identifiers_without_redirects = xref_targets.keys() - self._raw_redirects.keys() orphan_identifiers = self._raw_redirects.keys() - xref_targets.keys() @@ -124,7 +122,7 @@ def __init__(self, client_paths_with_server_redirects: dict[str, str]): super().__init__(self.__str__()) def __str__(self): - client_paths_with_server_redirects_list = "\n - ".join(f"{source} -> {dest}" for source, dest in self.client_paths_with_server_redirects.items()) + client_paths_with_server_redirects_list = "\n- ".join(f"{source} -> {dest}" for source, dest in self.client_paths_with_server_redirects.items()) return f""" **Client Paths with Server Redirects Found** A client redirect from a path that has a server-side redirect must not exist. @@ -145,10 +143,10 @@ def __init__(self, conflicts: set[str]): super().__init__(self.__str__()) def __str__(self): - conflict_list = "\n - ".join(sorted(self.conflicts)) + conflict_list = "\n- ".join(sorted(self.conflicts)) return f""" **Conflicting Anchors Found** -An identifier must not match the name of an anchor across any historical location of the same output path. +Identifiers must not be identical to any historical location's anchor of the same output path. The following identifiers voilate the above rule: - {conflict_list} @@ -166,7 +164,7 @@ def __init__(self, divergent: set[str]): super().__init__(self.__str__()) def __str__(self): - divergent_list = "\n - ".join(sorted(self.divergent)) + divergent_list = "\n- ".join(sorted(self.divergent)) return f""" **Divergent Redirects Found** A given historical path must correspond to only one identifier. @@ -187,7 +185,7 @@ def __init__(self, invalid: set[str]): super().__init__(self.__str__()) def __str__(self): - invalid_list = "\n - ".join(sorted(self.invalid)) + invalid_list = "\n- ".join(sorted(self.invalid)) return f""" **Invalid Current Paths Found** The head element of an identifier's corresponding historical location must be its current output location. @@ -205,12 +203,12 @@ def __init__(self, missing: set[str]): super().__init__(self.__str__()) def __str__(self): - missing_list = "\n - ".join(sorted(self.missing)) + missing_list = "\n- ".join(sorted(self.missing)) return f""" **Redirects Missing** -Every identifier present in the source files must have a mapping in the redirects. +Identifiers present in the source must have a mapping in the redirects. -The following identifiers voilate the above rule: +The following identifiers violate the above rule: - {missing_list} This can generally happen when: @@ -227,10 +225,10 @@ def __init__(self, orphans: set[str]): super().__init__(self.__str__()) def __str__(self): - orphan_list = "\n - ".join(sorted(self.orphans)) + orphan_list = "\n- ".join(sorted(self.orphans)) return f""" **Orphan Identifiers Found** -Every key of the redirects mapping must correspond to some identifier in the source files. +Keys of the redirects mapping must correspond to some identifier in the source. The following identifiers voilate the above rule: - {orphan_list} diff --git a/pkgs/tools/nix/nixos-render-docs/src/tests/test_redirects.py b/pkgs/tools/nix/nixos-render-docs/src/tests/test_redirects.py index b7bcffe1469f97..ee33daf68801a6 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/tests/test_redirects.py +++ b/pkgs/tools/nix/nixos-render-docs/src/tests/test_redirects.py @@ -86,7 +86,7 @@ def test_identifier_renamed(self): after.raise_errors() def test_leaf_identifier_moved_to_different_file(self): - """Test moving a leaf identifier to a different source file.""" + """Test moving a leaf identifier to a different output path.""" before = self.setup_boilerplate( sources={"foo.md": "# Foo {#foo}\n## Bar {#bar}"}, redirects={"foo": ["foo.html"], "bar": ["foo.html"]}, @@ -112,7 +112,7 @@ def test_leaf_identifier_moved_to_different_file(self): after.raise_errors() def test_non_leaf_identifier_moved_to_different_file(self): - """Test moving a non-leaf identifier to a different source file.""" + """Test moving a non-leaf identifier to a different output path.""" before = self.setup_boilerplate( sources={"foo.md": "# Foo {#foo}\n## Bar {#bar}\n### Baz {#baz}"}, redirects={"foo": ["foo.html"], "bar": ["foo.html"], "baz": ["foo.html"]},