rolfedh-doc-utils 0.1.16__tar.gz → 0.1.18__tar.gz

{rolfedh_doc_utils-0.1.16/rolfedh_doc_utils.egg-info → rolfedh_doc_utils-0.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.16
+Version: 0.1.18
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License

{rolfedh_doc_utils-0.1.16 → rolfedh_doc_utils-0.1.18}/doc_utils/unused_attributes.py

@@ -15,6 +15,29 @@ from pathlib import Path
 from typing import Set, List, Optional
 
 def parse_attributes_file(attr_file: str) -> Set[str]:
+    # AsciiDoc configuration attributes that control the processor itself
+    # These should be ignored as they won't appear in content
+    IGNORED_ATTRIBUTES = {
+        'data-uri',
+        'doctype',
+        'experimental',
+        'idprefix',
+        'imagesdir',
+        'includes',
+        'sectanchors',
+        'sectlinks',
+        'source-highlighter',
+        'linkattrs',
+        'toclevels',
+        'idseparator',
+        'icons',
+        'iconsdir',
+        'generated-dir',
+        'code-examples',
+        'doc-guides',
+        'doc-examples',
+    }
+
     attributes = set()
 
     # Check if file exists
@@ -30,7 +53,10 @@ def parse_attributes_file(attr_file: str) -> Set[str]:
             for line in f:
                 match = re.match(r'^:([\w-]+):', line.strip())
                 if match:
-                    attributes.add(match.group(1))
+                    attr_name = match.group(1)
+                    # Skip ignored configuration attributes
+                    if attr_name not in IGNORED_ATTRIBUTES:
+                        attributes.add(attr_name)
     except PermissionError:
         raise PermissionError(f"Permission denied reading file: {attr_file}")
     except UnicodeDecodeError as e:
@@ -50,13 +76,22 @@ def find_adoc_files(root_dir: str) -> List[str]:
 
 def scan_for_attribute_usage(adoc_files: List[str], attributes: Set[str]) -> Set[str]:
     used = set()
+    # Pattern for attribute references: {attribute-name}
     attr_pattern = re.compile(r'\{([\w-]+)\}')
+    # Patterns for conditional directives: ifdef::attr[], ifndef::attr[], endif::attr[]
+    conditional_pattern = re.compile(r'(?:ifdef|ifndef|endif)::([\w-]+)\[')
+
     for file in adoc_files:
         with open(file, 'r', encoding='utf-8') as f:
             for line in f:
+                # Check for {attribute} references
                 for match in attr_pattern.findall(line):
                     if match in attributes:
                         used.add(match)
+                # Check for ifdef::attribute[], ifndef::attribute[], endif::attribute[]
+                for match in conditional_pattern.findall(line):
+                    if match in attributes:
+                        used.add(match)
     return used
 
 def find_attributes_files(root_dir: str = '.') -> List[str]:
@@ -136,3 +171,44 @@ def find_unused_attributes(attr_file: str, adoc_root: str = '.') -> List[str]:
     used = scan_for_attribute_usage(adoc_files, attributes)
     unused = sorted(attributes - used)
     return unused
+
+
+def comment_out_unused_attributes(attr_file: str, unused_attrs: List[str]) -> int:
+    """
+    Comment out unused attributes in the attributes file.
+
+    Args:
+        attr_file: Path to the attributes file
+        unused_attrs: List of unused attribute names
+
+    Returns:
+        Number of attributes commented out
+    """
+    if not unused_attrs:
+        return 0
+
+    # Read the file
+    with open(attr_file, 'r', encoding='utf-8') as f:
+        lines = f.readlines()
+
+    # Create a set for faster lookup
+    unused_set = set(unused_attrs)
+    commented_count = 0
+
+    # Process each line
+    new_lines = []
+    for line in lines:
+        # Check if this line defines an attribute
+        match = re.match(r'^:([\w-]+):', line)
+        if match and match.group(1) in unused_set:
+            # Comment out this line
+            new_lines.append(f'// Unused {line}')
+            commented_count += 1
+        else:
+            new_lines.append(line)
+
+    # Write back to the file
+    with open(attr_file, 'w', encoding='utf-8') as f:
+        f.writelines(new_lines)
+
+    return commented_count

{rolfedh_doc_utils-0.1.16 → rolfedh_doc_utils-0.1.18}/find_unused_attributes.py

@@ -12,7 +12,7 @@ import argparse
 import os
 import sys
 from datetime import datetime
-from doc_utils.unused_attributes import find_unused_attributes, find_attributes_files, select_attributes_file
+from doc_utils.unused_attributes import find_unused_attributes, find_attributes_files, select_attributes_file, comment_out_unused_attributes
 from doc_utils.spinner import Spinner
 from doc_utils.version_check import check_version_on_startup
 
@@ -26,6 +26,7 @@ def main():
         help='Path to the attributes file. If not specified, auto-discovers attributes files.'
     )
     parser.add_argument('-o', '--output', action='store_true', help='Write results to a timestamped txt file in your home directory.')
+    parser.add_argument('-c', '--comment-out', action='store_true', help='Comment out unused attributes in the attributes file with "// Unused".')
     args = parser.parse_args()
 
     # Determine which attributes file to use
@@ -84,6 +85,16 @@ def main():
             f.write(output + '\n')
         print(f'Results written to: {filename}')
 
+    if args.comment_out and output:
+        # Ask for confirmation before modifying the file
+        print(f'\nThis will comment out {len(unused)} unused attributes in: {attr_file}')
+        response = input('Continue? (y/n): ').strip().lower()
+        if response == 'y':
+            commented_count = comment_out_unused_attributes(attr_file, unused)
+            print(f'Commented out {commented_count} unused attributes in: {attr_file}')
+        else:
+            print('Operation cancelled.')
+
     return 0
 
 if __name__ == '__main__':

{rolfedh_doc_utils-0.1.16 → rolfedh_doc_utils-0.1.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rolfedh-doc-utils"
-version = "0.1.16"
+version = "0.1.18"
 description = "CLI tools for AsciiDoc documentation projects"
 readme = "README.md"
 requires-python = ">=3.8"

{rolfedh_doc_utils-0.1.16 → rolfedh_doc_utils-0.1.18/rolfedh_doc_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.16
+Version: 0.1.18
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License

rolfedh_doc_utils-0.1.18/tests/test_unused_attributes.py

@@ -0,0 +1,199 @@
+import os
+import tempfile
+from doc_utils.unused_attributes import parse_attributes_file, find_adoc_files, scan_for_attribute_usage, find_unused_attributes, comment_out_unused_attributes
+
+def make_file(path, content):
+    with open(path, 'w', encoding='utf-8') as f:
+        f.write(content)
+
+def test_parse_attributes_file():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        make_file(attr_path, ":foo: bar\n:bar: baz\n:unused: 123\n")
+        attrs = parse_attributes_file(attr_path)
+        assert 'foo' in attrs
+        assert 'bar' in attrs
+        assert 'unused' in attrs
+
+def test_find_adoc_files_and_usage():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        make_file(attr_path, ":foo: bar\n:bar: baz\n:unused: 123\n")
+        adoc1 = os.path.join(tmpdir, 'a.adoc')
+        adoc2 = os.path.join(tmpdir, 'b.adoc')
+        make_file(adoc1, "This uses {foo} and {bar}.")
+        make_file(adoc2, "No attributes here.")
+        adoc_files = find_adoc_files(tmpdir)
+        attrs = parse_attributes_file(attr_path)
+        used = scan_for_attribute_usage(adoc_files, attrs)
+        assert 'foo' in used
+        assert 'bar' in used
+        assert 'unused' not in used
+
+def test_find_unused_attributes():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        make_file(attr_path, ":foo: bar\n:bar: baz\n:unused: 123\n")
+        adoc1 = os.path.join(tmpdir, 'a.adoc')
+        adoc2 = os.path.join(tmpdir, 'b.adoc')
+        make_file(adoc1, "This uses {foo} and {bar}.")
+        make_file(adoc2, "No attributes here.")
+        unused = find_unused_attributes(attr_path, tmpdir)
+        assert 'unused' in unused
+        assert 'foo' not in unused
+        assert 'bar' not in unused
+
+def test_conditional_directives_ifdef():
+    """Test that ifdef::attribute:: is recognized as usage."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        make_file(attr_path, ":rh-only:\n:downstream:\n:unused:\n")
+        adoc1 = os.path.join(tmpdir, 'test.adoc')
+        make_file(adoc1, "ifdef::rh-only[]\nSome content\nendif::rh-only[]\n")
+        attrs = parse_attributes_file(attr_path)
+        adoc_files = find_adoc_files(tmpdir)
+        used = scan_for_attribute_usage(adoc_files, attrs)
+        assert 'rh-only' in used
+        assert 'downstream' not in used
+        assert 'unused' not in used
+
+def test_conditional_directives_ifndef():
+    """Test that ifndef::attribute:: is recognized as usage."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        make_file(attr_path, ":no-feature:\n:unused:\n")
+        adoc1 = os.path.join(tmpdir, 'test.adoc')
+        make_file(adoc1, "ifndef::no-feature[]\nContent when feature exists\nendif::no-feature[]\n")
+        attrs = parse_attributes_file(attr_path)
+        adoc_files = find_adoc_files(tmpdir)
+        used = scan_for_attribute_usage(adoc_files, attrs)
+        assert 'no-feature' in used
+        assert 'unused' not in used
+
+def test_conditional_directives_endif():
+    """Test that endif::attribute:: is recognized as usage."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        make_file(attr_path, ":my-attr:\n:unused:\n")
+        adoc1 = os.path.join(tmpdir, 'test.adoc')
+        make_file(adoc1, "ifdef::my-attr[]\nSome content\nendif::my-attr[]\n")
+        attrs = parse_attributes_file(attr_path)
+        adoc_files = find_adoc_files(tmpdir)
+        used = scan_for_attribute_usage(adoc_files, attrs)
+        assert 'my-attr' in used
+        assert 'unused' not in used
+
+def test_mixed_usage_patterns():
+    """Test attributes used in both {attr} and ifdef::attr:: forms."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        make_file(attr_path, ":version: 1.0\n:rh-only:\n:unused:\n")
+        adoc1 = os.path.join(tmpdir, 'test.adoc')
+        make_file(adoc1, "Version {version}\nifdef::rh-only[]\nRH content\nendif::rh-only[]\n")
+        unused = find_unused_attributes(attr_path, tmpdir)
+        assert 'unused' in unused
+        assert 'version' not in unused
+        assert 'rh-only' not in unused
+
+def test_no_prefix_attributes():
+    """Test attributes with 'no-' prefix used in ifndef directives."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        make_file(attr_path, ":no-quarkus-security-jpa-reactive:\n:no-webauthn-authentication:\n:unused:\n")
+        adoc1 = os.path.join(tmpdir, 'test.adoc')
+        make_file(adoc1, """
+ifndef::no-quarkus-security-jpa-reactive[]
+Content about JPA reactive security
+endif::no-quarkus-security-jpa-reactive[]
+
+ifndef::no-webauthn-authentication[]
+Content about WebAuthn
+endif::no-webauthn-authentication[]
+""")
+        unused = find_unused_attributes(attr_path, tmpdir)
+        assert 'unused' in unused
+        assert 'no-quarkus-security-jpa-reactive' not in unused
+        assert 'no-webauthn-authentication' not in unused
+
+def test_comment_out_unused_attributes():
+    """Test commenting out unused attributes in the attributes file."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        original_content = """:version: 1.0
+:product: MyApp
+:unused1: value1
+:unused2: value2
+:rh-only:
+"""
+        make_file(attr_path, original_content)
+
+        adoc1 = os.path.join(tmpdir, 'test.adoc')
+        make_file(adoc1, "Version {version} Product {product}\nifdef::rh-only[]\nContent\nendif::rh-only[]\n")
+
+        # Find unused attributes
+        unused = find_unused_attributes(attr_path, tmpdir)
+        assert 'unused1' in unused
+        assert 'unused2' in unused
+        assert 'version' not in unused
+        assert 'product' not in unused
+        assert 'rh-only' not in unused
+
+        # Comment out unused attributes
+        count = comment_out_unused_attributes(attr_path, unused)
+        assert count == 2
+
+        # Verify the file was modified correctly
+        with open(attr_path, 'r') as f:
+            content = f.read()
+
+        assert '// Unused :unused1: value1\n' in content
+        assert '// Unused :unused2: value2\n' in content
+        assert ':version: 1.0\n' in content
+        assert ':product: MyApp\n' in content
+        assert ':rh-only:\n' in content
+
+def test_comment_out_empty_list():
+    """Test that comment_out_unused_attributes handles empty list correctly."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        original_content = ":version: 1.0\n:product: MyApp\n"
+        make_file(attr_path, original_content)
+
+        # Comment out with empty list
+        count = comment_out_unused_attributes(attr_path, [])
+        assert count == 0
+
+        # Verify file was not modified
+        with open(attr_path, 'r') as f:
+            content = f.read()
+
+        assert content == original_content
+
+def test_comment_out_preserves_formatting():
+    """Test that commenting out preserves line formatting and comments."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        attr_path = os.path.join(tmpdir, 'attributes.adoc')
+        original_content = """// This is a comment
+:version: 1.0
+
+:unused: value with spaces
+// Another comment
+:product: MyApp
+"""
+        make_file(attr_path, original_content)
+
+        adoc1 = os.path.join(tmpdir, 'test.adoc')
+        make_file(adoc1, "Version {version} Product {product}\n")
+
+        unused = find_unused_attributes(attr_path, tmpdir)
+        count = comment_out_unused_attributes(attr_path, unused)
+        assert count == 1
+
+        with open(attr_path, 'r') as f:
+            content = f.read()
+
+        assert '// This is a comment\n' in content
+        assert '// Unused :unused: value with spaces\n' in content
+        assert '// Another comment\n' in content
+        assert ':version: 1.0\n' in content
+        assert ':product: MyApp\n' in content

rolfedh_doc_utils-0.1.16/tests/test_unused_attributes.py

@@ -1,44 +0,0 @@
-import os
-import tempfile
-from doc_utils.unused_attributes import parse_attributes_file, find_adoc_files, scan_for_attribute_usage, find_unused_attributes
-
-def make_file(path, content):
-    with open(path, 'w', encoding='utf-8') as f:
-        f.write(content)
-
-def test_parse_attributes_file():
-    with tempfile.TemporaryDirectory() as tmpdir:
-        attr_path = os.path.join(tmpdir, 'attributes.adoc')
-        make_file(attr_path, ":foo: bar\n:bar: baz\n:unused: 123\n")
-        attrs = parse_attributes_file(attr_path)
-        assert 'foo' in attrs
-        assert 'bar' in attrs
-        assert 'unused' in attrs
-
-def test_find_adoc_files_and_usage():
-    with tempfile.TemporaryDirectory() as tmpdir:
-        attr_path = os.path.join(tmpdir, 'attributes.adoc')
-        make_file(attr_path, ":foo: bar\n:bar: baz\n:unused: 123\n")
-        adoc1 = os.path.join(tmpdir, 'a.adoc')
-        adoc2 = os.path.join(tmpdir, 'b.adoc')
-        make_file(adoc1, "This uses {foo} and {bar}.")
-        make_file(adoc2, "No attributes here.")
-        adoc_files = find_adoc_files(tmpdir)
-        attrs = parse_attributes_file(attr_path)
-        used = scan_for_attribute_usage(adoc_files, attrs)
-        assert 'foo' in used
-        assert 'bar' in used
-        assert 'unused' not in used
-
-def test_find_unused_attributes():
-    with tempfile.TemporaryDirectory() as tmpdir:
-        attr_path = os.path.join(tmpdir, 'attributes.adoc')
-        make_file(attr_path, ":foo: bar\n:bar: baz\n:unused: 123\n")
-        adoc1 = os.path.join(tmpdir, 'a.adoc')
-        adoc2 = os.path.join(tmpdir, 'b.adoc')
-        make_file(adoc1, "This uses {foo} and {bar}.")
-        make_file(adoc2, "No attributes here.")
-        unused = find_unused_attributes(attr_path, tmpdir)
-        assert 'unused' in unused
-        assert 'foo' not in unused
-        assert 'bar' not in unused