rolfedh-doc-utils 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

find_unused_attributes.py

@@ -1,23 +1,61 @@
 """
 Find Unused AsciiDoc Attributes
 
-Scans a user-specified attributes file (e.g., attributes.adoc) for attribute definitions (e.g., :version: 1.1), then recursively scans all .adoc files in the current directory (ignoring symlinks) for usages of those attributes (e.g., {version}).
+Scans an attributes file for attribute definitions (e.g., :version: 1.1), then recursively scans all .adoc files in the current directory (ignoring symlinks) for usages of those attributes (e.g., {version}).
+
+If no attributes file is specified, the tool will auto-discover attributes files in the repository and let you choose one interactively.
 
 Any attribute defined but not used in any .adoc file is reported as NOT USED in both the command line output and a timestamped output file.
 """
 
 import argparse
 import os
+import sys
 from datetime import datetime
-from doc_utils.unused_attributes import find_unused_attributes
+from doc_utils.unused_attributes import find_unused_attributes, find_attributes_files, select_attributes_file
 
 def main():
     parser = argparse.ArgumentParser(description='Find unused AsciiDoc attributes.')
-    parser.add_argument('attributes_file', help='Path to the attributes.adoc file to scan for attribute definitions.')
+    parser.add_argument(
+        'attributes_file',
+        nargs='?',  # Make it optional
+        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.')
     args = parser.parse_args()
 
-    unused = find_unused_attributes(args.attributes_file, '.')
+    # Determine which attributes file to use
+    if args.attributes_file:
+        # User specified a file
+        attr_file = args.attributes_file
+    else:
+        # Auto-discover attributes files
+        print("Searching for attributes files...")
+        attributes_files = find_attributes_files('.')
+
+        if not attributes_files:
+            print("No attributes files found in the repository.")
+            print("You can specify a file directly: find-unused-attributes <path-to-attributes-file>")
+            return 1
+
+        attr_file = select_attributes_file(attributes_files)
+        if not attr_file:
+            print("No attributes file selected.")
+            return 1
+
+    try:
+        unused = find_unused_attributes(attr_file, '.')
+    except FileNotFoundError as e:
+        print(f"Error: {e}")
+        print(f"\nPlease ensure the file '{attr_file}' exists.")
+        print("Usage: find-unused-attributes [<path-to-attributes-file>]")
+        return 1
+    except (ValueError, PermissionError) as e:
+        print(f"Error: {e}")
+        return 1
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        return 1
 
     lines = [f":{attr}:  NOT USED" for attr in unused]
     output = '\n'.join(lines)
@@ -33,9 +71,12 @@ def main():
         home_dir = os.path.expanduser('~')
         filename = os.path.join(home_dir, f'unused_attributes_{timestamp}.txt')
         with open(filename, 'w', encoding='utf-8') as f:
-            f.write('Unused attributes in ' + args.attributes_file + '\n')
+            f.write('Unused attributes in ' + attr_file + '\n')
             f.write(output + '\n')
         print(f'Results written to: {filename}')
 
+    return 0
+
 if __name__ == '__main__':
-    main()
+    import sys
+    sys.exit(main())

{rolfedh_doc_utils-0.1.9.dist-info → rolfedh_doc_utils-0.1.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.9
+Version: 0.1.11
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -79,8 +79,10 @@ pip install -e .
 
 | Tool | Description | Usage |
 |------|-------------|-------|
-| **`replace-link-attributes`** | Resolves Vale LinkAttribute violations by replacing attributes in link URLs | `replace-link-attributes --dry-run` |
-| **`format-asciidoc-spacing`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run modules/` |
+| **`validate-links`** [EXPERIMENTAL] | Validates all links in documentation, with URL transposition for preview environments | `validate-links --transpose "https://prod--https://preview"` |
+| **`extract-link-attributes`** | Extracts link/xref macros with attributes into reusable definitions | `extract-link-attributes --dry-run` |
+| **`replace-link-attributes`** | Resolves Vale LinkAttribute issues by replacing attributes in link URLs | `replace-link-attributes --dry-run` |
+| **`format-asciidoc-spacing`** [EXPERIMENTAL] | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run modules/` |
 | **`check-scannability`** | Analyzes readability (sentence/paragraph length) | `check-scannability --max-words 25` |
 | **`archive-unused-files`** | Finds and archives unreferenced .adoc files | `archive-unused-files` (preview)<br>`archive-unused-files --archive` (execute) |
 | **`archive-unused-images`** | Finds and archives unreferenced images | `archive-unused-images` (preview)<br>`archive-unused-images --archive` (execute) |

{rolfedh_doc_utils-0.1.9.dist-info → rolfedh_doc_utils-0.1.11.dist-info}/RECORD

@@ -1,21 +1,25 @@
 archive_unused_files.py,sha256=KMC5a1WL3rZ5owoVnncvfpT1YeMKbVXq9giHvadDgbM,1936
 archive_unused_images.py,sha256=PG2o3haovYckgfhoPhl6KRG_a9czyZuqlLkzkupKTCY,1526
 check_scannability.py,sha256=gcM-vFXKHGP_yFBz7-V5xbXWhIMmtMzBYIGwP9CFbzI,5140
-find_unused_attributes.py,sha256=fk-K32eoCVHxoj7RiBNgSmX1arBLuwYfdSAOMc-wIx0,1677
+extract_link_attributes.py,sha256=utDM1FE-VEr649HhIH5BreXvxDNLnnAJO9dB5rs5f9Q,2535
+find_unused_attributes.py,sha256=V8qI7O0u18ExbSho-hLfyBeRVqowLKGrFugY55JxZN0,3023
 format_asciidoc_spacing.py,sha256=ROp-cdMs2_hk8H4z5ljT0iDgGtsiECZ8TVjjcN_oOWE,3874
 replace_link_attributes.py,sha256=vg_aufw7dKXvh_epCKRNq_hEBMU_9crZ_JyJPpxSMNk,6454
+validate_links.py,sha256=DoSB0h3mmjzTY2f0oN6ybTP6jCNkzN7T3qM6oXc2AwE,5585
 doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
+doc_utils/extract_link_attributes.py,sha256=qBpJuTXNrhy15klpqC0iELZzcSLztEzMSmhEnKyQZT0,15574
 doc_utils/file_utils.py,sha256=fpTh3xx759sF8sNocdn_arsP3KAv8XA6cTQTAVIZiZg,4247
 doc_utils/format_asciidoc_spacing.py,sha256=XnVJekaj39aDzjV3xFKl58flM41AaJzejxNYJIIAMz0,10139
 doc_utils/replace_link_attributes.py,sha256=kBiePbxjQn3O2rzqmYY8Mqy_mJgZ6yw048vSZ5SSB5E,6587
 doc_utils/scannability.py,sha256=XwlmHqDs69p_V36X7DLjPTy0DUoLszSGqYjJ9wE-3hg,982
 doc_utils/topic_map_parser.py,sha256=tKcIO1m9r2K6dvPRGue58zqMr0O2zKU1gnZMzEE3U6o,4571
 doc_utils/unused_adoc.py,sha256=2cbqcYr1os2EhETUU928BlPRlsZVSdI00qaMhqjSIqQ,5263
-doc_utils/unused_attributes.py,sha256=HBgmHelqearfWl3TTC2bZGiJytjLADIgiGQUNKqXXPg,1847
+doc_utils/unused_attributes.py,sha256=EjTtWIKW_aXsR1JOgw5RSDVAqitJ_NfRMVOXVGaiWTY,5282
 doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,1456
-rolfedh_doc_utils-0.1.9.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.9.dist-info/METADATA,sha256=QmlwozZ8j3S2dnbZhsQpCr4JIDTyyjKpMCUYWnkCOTA,7041
-rolfedh_doc_utils-0.1.9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.9.dist-info/entry_points.txt,sha256=w5FlyLk-L2rtzYsMuTo8OVxYPo4nm4zRiArBTYqVud0,326
-rolfedh_doc_utils-0.1.9.dist-info/top_level.txt,sha256=YrJAJFSkY9RKoHGDmrFCwsMVZS3Azw6ewzR2b081qCU,143
-rolfedh_doc_utils-0.1.9.dist-info/RECORD,,
+doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
+rolfedh_doc_utils-0.1.11.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.11.dist-info/METADATA,sha256=22seO4nEGTjlibUZ8tPRxTFyYpmLRsfY7sZssteQl1g,7386
+rolfedh_doc_utils-0.1.11.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.11.dist-info/entry_points.txt,sha256=2J4Ojc3kkuArpe2xcUOPc0LxSWCmnctvw8hy8zpnbO4,418
+rolfedh_doc_utils-0.1.11.dist-info/top_level.txt,sha256=1w0JWD7w7gnM5Sga2K4fJieNZ7CHPTAf0ozYk5iIlmo,182
+rolfedh_doc_utils-0.1.11.dist-info/RECORD,,

{rolfedh_doc_utils-0.1.9.dist-info → rolfedh_doc_utils-0.1.11.dist-info}/entry_points.txt

@@ -2,6 +2,8 @@
 archive-unused-files = archive_unused_files:main
 archive-unused-images = archive_unused_images:main
 check-scannability = check_scannability:main
+extract-link-attributes = extract_link_attributes:main
 find-unused-attributes = find_unused_attributes:main
 format-asciidoc-spacing = format_asciidoc_spacing:main
 replace-link-attributes = replace_link_attributes:main
+validate-links = validate_links:main

{rolfedh_doc_utils-0.1.9.dist-info → rolfedh_doc_utils-0.1.11.dist-info}/top_level.txt

@@ -2,6 +2,8 @@ archive_unused_files
 archive_unused_images
 check_scannability
 doc_utils
+extract_link_attributes
 find_unused_attributes
 format_asciidoc_spacing
 replace_link_attributes
+validate_links

validate_links.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""
+Validate links in AsciiDoc documentation.
+
+This tool checks all links in AsciiDoc files for validity, including:
+- External HTTP/HTTPS links
+- Internal cross-references (xref)
+- Image paths
+"""
+
+import argparse
+import sys
+import json
+from doc_utils.validate_links import LinkValidator, parse_transpositions, format_results
+
+
+def main():
+    """Main entry point for the validate-links CLI tool."""
+    parser = argparse.ArgumentParser(
+        description='Validate links in AsciiDoc documentation',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Basic validation
+  validate-links
+
+  # Validate against preview environment
+  validate-links --transpose "https://docs.redhat.com--https://preview.docs.redhat.com"
+
+  # Multiple transpositions
+  validate-links \\
+    --transpose "https://docs.redhat.com--https://preview.docs.redhat.com" \\
+    --transpose "https://access.redhat.com--https://stage.access.redhat.com"
+
+  # With specific options
+  validate-links \\
+    --transpose "https://docs.example.com--https://preview.example.com" \\
+    --attributes-file common-attributes.adoc \\
+    --timeout 15 \\
+    --retry 3 \\
+    --parallel 20 \\
+    --exclude-domain localhost \\
+    --exclude-domain example.com
+
+  # Export results to JSON
+  validate-links --output report.json --format json
+        """
+    )
+
+    parser.add_argument(
+        '--transpose',
+        action='append',
+        help='Transpose URLs from production to preview/staging (format: from_url--to_url)'
+    )
+
+    parser.add_argument(
+        '--attributes-file',
+        help='Path to the AsciiDoc attributes file'
+    )
+
+    parser.add_argument(
+        '--scan-dir',
+        action='append',
+        help='Directory to scan for .adoc files (can be used multiple times, default: current directory)'
+    )
+
+    parser.add_argument(
+        '--timeout',
+        type=int,
+        default=10,
+        help='Timeout in seconds for each URL check (default: 10)'
+    )
+
+    parser.add_argument(
+        '--retry',
+        type=int,
+        default=3,
+        help='Number of retries for failed URLs (default: 3)'
+    )
+
+    parser.add_argument(
+        '--parallel',
+        type=int,
+        default=10,
+        help='Number of parallel URL checks (default: 10)'
+    )
+
+    parser.add_argument(
+        '--cache-duration',
+        type=int,
+        default=3600,
+        help='Cache duration in seconds (default: 3600)'
+    )
+
+    parser.add_argument(
+        '--exclude-domain',
+        action='append',
+        dest='exclude_domains',
+        help='Domain to exclude from validation (can be used multiple times)'
+    )
+
+    parser.add_argument(
+        '--no-cache',
+        action='store_true',
+        help='Disable caching of validation results'
+    )
+
+    parser.add_argument(
+        '--output',
+        help='Output file for results'
+    )
+
+    parser.add_argument(
+        '--format',
+        choices=['text', 'json', 'junit'],
+        default='text',
+        help='Output format (default: text)'
+    )
+
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='Show verbose output including warnings'
+    )
+
+    parser.add_argument(
+        '--fail-on-broken',
+        action='store_true',
+        help='Exit with error code if broken links are found'
+    )
+
+    args = parser.parse_args()
+
+    # Parse transpositions
+    transpositions = parse_transpositions(args.transpose)
+
+    # Show configuration
+    print("Validating links in documentation...")
+    if args.attributes_file:
+        print(f"Loading attributes from {args.attributes_file}")
+    if transpositions:
+        print("\nURL Transposition Rules:")
+        for from_url, to_url in transpositions:
+            print(f"  {from_url} → {to_url}")
+        print()
+
+    # Create validator
+    validator = LinkValidator(
+        timeout=args.timeout,
+        retry=args.retry,
+        parallel=args.parallel,
+        cache_duration=args.cache_duration if not args.no_cache else 0,
+        transpositions=transpositions
+    )
+
+    try:
+        # Run validation
+        results = validator.validate_all(
+            scan_dirs=args.scan_dir,
+            attributes_file=args.attributes_file,
+            exclude_domains=args.exclude_domains
+        )
+
+        # Format output
+        if args.format == 'json':
+            output = json.dumps(results, indent=2)
+        elif args.format == 'junit':
+            # TODO: Implement JUnit XML format
+            output = format_results(results, verbose=args.verbose)
+        else:
+            output = format_results(results, verbose=args.verbose)
+
+        # Save or print output
+        if args.output:
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(output)
+            print(f"Results saved to {args.output}")
+            # Still print summary to console
+            if args.format != 'text':
+                summary = results['summary']
+                print(f"\nSummary: {summary['valid']} valid, {summary['broken']} broken, "
+                      f"{summary['warnings']} warnings")
+        else:
+            print(output)
+
+        # Exit code
+        if args.fail_on_broken and results['summary']['broken'] > 0:
+            sys.exit(1)
+
+    except KeyboardInterrupt:
+        print("\nValidation cancelled.")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()