fix: update docstrings

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];

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}

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"]},