rolfedh-doc-utils 0.1.15__py3-none-any.whl → 0.1.17__py3-none-any.whl

archive_unused_files.py

@@ -9,10 +9,13 @@ For full documentation and usage examples, see archive_unused_files.md in this d
 
 import argparse
 from doc_utils.unused_adoc import find_unused_adoc
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.file_utils import parse_exclude_list_file
 
 from doc_utils.spinner import Spinner
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     parser = argparse.ArgumentParser(
         description='Archive unused AsciiDoc files.',
         epilog='By default, automatically discovers all modules and assemblies directories in the repository.'

archive_unused_images.py

@@ -8,10 +8,13 @@ For full documentation and usage examples, see archive_unused_files.md in this d
 
 import argparse
 from doc_utils.unused_images import find_unused_images
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.file_utils import parse_exclude_list_file
 
 from doc_utils.spinner import Spinner
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     parser = argparse.ArgumentParser(description='Archive unused image files.')
     parser.add_argument('--archive', action='store_true', help='Move the files to a dated zip in the archive directory.')
     parser.add_argument('--exclude-dir', action='append', default=[], help='Directory to exclude (can be used multiple times).')

check_scannability.py

@@ -17,6 +17,7 @@ import sys
 import argparse
 from datetime import datetime
 from doc_utils.scannability import check_scannability
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.file_utils import collect_files, parse_exclude_list_file
 
 from doc_utils.spinner import Spinner
@@ -27,6 +28,8 @@ def print_help():
     print(__doc__)
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     # Manual check for -h or --help to display the full docstring
     if '-h' in sys.argv or '--help' in sys.argv:
         print_help()

doc_utils/unused_attributes.py

@@ -50,13 +50,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 +145,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

doc_utils/version_check.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""
+Version checking utility for doc-utils.
+
+Checks PyPI for the latest version and notifies users if an update is available.
+Includes caching to avoid excessive PyPI requests.
+"""
+
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+from datetime import datetime, timedelta
+from importlib.metadata import version as get_installed_version
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def get_cache_dir() -> Path:
+    """Get the cache directory for version check data."""
+    # Use XDG_CACHE_HOME if set, otherwise ~/.cache
+    cache_home = os.environ.get('XDG_CACHE_HOME')
+    if cache_home:
+        cache_dir = Path(cache_home) / 'doc-utils'
+    else:
+        cache_dir = Path.home() / '.cache' / 'doc-utils'
+
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def get_cache_file() -> Path:
+    """Get the cache file path."""
+    return get_cache_dir() / 'version_check.json'
+
+
+def read_cache() -> Optional[dict]:
+    """Read version check cache."""
+    cache_file = get_cache_file()
+    if not cache_file.exists():
+        return None
+
+    try:
+        with open(cache_file, 'r') as f:
+            data = json.load(f)
+            # Check if cache is still valid (24 hours)
+            last_check = datetime.fromisoformat(data['last_check'])
+            if datetime.now() - last_check < timedelta(hours=24):
+                return data
+    except (json.JSONDecodeError, KeyError, ValueError):
+        pass
+
+    return None
+
+
+def write_cache(latest_version: str, current_version: str):
+    """Write version check cache."""
+    cache_file = get_cache_file()
+    data = {
+        'last_check': datetime.now().isoformat(),
+        'latest_version': latest_version,
+        'current_version': current_version,
+    }
+
+    try:
+        with open(cache_file, 'w') as f:
+            json.dump(data, f)
+    except Exception:
+        # Silently fail if we can't write cache
+        pass
+
+
+def fetch_latest_version() -> Optional[str]:
+    """Fetch the latest version from PyPI."""
+    try:
+        # Use PyPI JSON API
+        url = 'https://pypi.org/pypi/rolfedh-doc-utils/json'
+        with urllib.request.urlopen(url, timeout=2) as response:
+            data = json.loads(response.read())
+            return data['info']['version']
+    except (urllib.error.URLError, json.JSONDecodeError, KeyError, TimeoutError):
+        # Silently fail if we can't reach PyPI
+        return None
+
+
+def parse_version(version_str: str) -> Tuple[int, ...]:
+    """Parse version string into tuple of integers for comparison."""
+    try:
+        # Remove any pre-release or dev suffixes
+        version_str = version_str.split('+')[0].split('-')[0]
+        return tuple(int(x) for x in version_str.split('.'))
+    except (ValueError, AttributeError):
+        return (0,)
+
+
+def check_for_update(force_check: bool = False) -> Optional[str]:
+    """
+    Check if a newer version is available.
+
+    Args:
+        force_check: If True, bypass cache and always check PyPI
+
+    Returns:
+        The latest version string if an update is available, None otherwise
+    """
+    try:
+        current_version = get_installed_version('rolfedh-doc-utils')
+    except Exception:
+        # Can't determine installed version
+        return None
+
+    # Check cache first (unless forced)
+    if not force_check:
+        cache_data = read_cache()
+        if cache_data:
+            latest_version = cache_data['latest_version']
+            # Only notify if there's a newer version
+            if parse_version(latest_version) > parse_version(current_version):
+                return latest_version
+            return None
+
+    # Fetch from PyPI
+    latest_version = fetch_latest_version()
+    if not latest_version:
+        return None
+
+    # Cache the result
+    write_cache(latest_version, current_version)
+
+    # Check if update is available
+    if parse_version(latest_version) > parse_version(current_version):
+        return latest_version
+
+    return None
+
+
+def show_update_notification(latest_version: str, current_version: str = None):
+    """Show update notification to user."""
+    if not current_version:
+        try:
+            current_version = get_installed_version('rolfedh-doc-utils')
+        except Exception:
+            current_version = 'unknown'
+
+    # Use stderr to avoid interfering with tool output
+    print(f"\n📦 Update available: {current_version} → {latest_version}", file=sys.stderr)
+    print(f"   Run: pip install --upgrade rolfedh-doc-utils", file=sys.stderr)
+    print("", file=sys.stderr)
+
+
+def check_version_on_startup():
+    """
+    Check for updates on tool startup.
+
+    This should be called early in the main() function of each CLI tool.
+    It runs asynchronously and won't block the tool execution.
+    """
+    # Skip version check in certain conditions
+    if any([
+        os.environ.get('DOC_UTILS_NO_VERSION_CHECK'),  # User opt-out
+        os.environ.get('CI'),  # Running in CI
+        not sys.stderr.isatty(),  # Not running in terminal
+    ]):
+        return
+
+    try:
+        latest_version = check_for_update()
+        if latest_version:
+            show_update_notification(latest_version)
+    except Exception:
+        # Never let version checking break the tool
+        pass
+
+
+def disable_version_check():
+    """
+    Instructions for disabling version check.
+
+    Users can disable by setting DOC_UTILS_NO_VERSION_CHECK environment variable.
+    """
+    print("To disable version checking, set the environment variable:")
+    print("  export DOC_UTILS_NO_VERSION_CHECK=1")
+    print("\nOr add it to your shell configuration file.")
+
+
+if __name__ == "__main__":
+    # For testing/debugging
+    import argparse
+    parser = argparse.ArgumentParser(description="Check for doc-utils updates")
+    parser.add_argument('--force', action='store_true', help='Force check (bypass cache)')
+    parser.add_argument('--disable-instructions', action='store_true',
+                       help='Show instructions for disabling version check')
+    args = parser.parse_args()
+
+    if args.disable_instructions:
+        disable_version_check()
+    else:
+        latest = check_for_update(force_check=args.force)
+        if latest:
+            show_update_notification(latest)
+        else:
+            print("You are running the latest version!")

extract_link_attributes.py

@@ -10,9 +10,12 @@ attribute references.
 import argparse
 import sys
 from doc_utils.extract_link_attributes import extract_link_attributes
+from doc_utils.version_check import check_version_on_startup
 
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     """Main entry point for the extract-link-attributes CLI tool."""
     parser = argparse.ArgumentParser(
         description='Extract link and xref macros containing attributes into attribute definitions',

find_unused_attributes.py

@@ -12,10 +12,13 @@ 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
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     parser = argparse.ArgumentParser(description='Find unused AsciiDoc attributes.')
     parser.add_argument(
         'attributes_file',
@@ -23,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
@@ -81,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__':

format_asciidoc_spacing.py

@@ -10,6 +10,7 @@ import sys
 from pathlib import Path
 
 from doc_utils.format_asciidoc_spacing import process_file, find_adoc_files
+from doc_utils.version_check import check_version_on_startup
 
 
 from doc_utils.spinner import Spinner
@@ -27,6 +28,8 @@ def print_colored(message: str, color: str = Colors.NC) -> None:
 
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     """Main entry point"""
     parser = argparse.ArgumentParser(
         description="Format AsciiDoc files to ensure proper spacing",

replace_link_attributes.py

@@ -19,6 +19,7 @@ from doc_utils.replace_link_attributes import (
     replace_link_attributes_in_file,
     find_adoc_files
 )
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.spinner import Spinner
 
 
@@ -83,6 +84,8 @@ def prompt_for_attributes_file(attributes_files: list[Path]) -> Optional[Path]:
 
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     parser = argparse.ArgumentParser(
         description='Replace AsciiDoc attributes within link macros with their actual values.'
     )

{rolfedh_doc_utils-0.1.15.dist-info → rolfedh_doc_utils-0.1.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.15
+Version: 0.1.17
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -190,11 +190,27 @@ Before submitting PRs:
 
 ## 📊 Project Status
 
-- **Latest Version**: 0.1.6
+- **Latest Version**: 0.1.16 (with automatic update notifications)
 - **Python Support**: 3.8+
-- **Test Coverage**: 66+ tests (100% passing)
+- **Test Coverage**: 112+ tests (100% passing)
 - **Dependencies**: Minimal (PyYAML for OpenShift-docs support)
 
+### 🔔 Update Notifications
+
+All tools now check for updates automatically and notify you when a new version is available:
+
+```
+📦 Update available: 0.1.15 → 0.1.16
+   Run: pip install --upgrade rolfedh-doc-utils
+```
+
+To disable update checks, set the environment variable:
+```bash
+export DOC_UTILS_NO_VERSION_CHECK=1
+```
+
+Update checks are cached for 24 hours to minimize network requests.
+
 ## 🔗 Resources
 
 - [Documentation](https://rolfedh.github.io/doc-utils/)

rolfedh_doc_utils-0.1.17.dist-info/RECORD

@@ -0,0 +1,27 @@
+archive_unused_files.py,sha256=VL4hEN40CTYJzScyevY1fn7Fs2O083qfJUYdrv5JxxM,2142
+archive_unused_images.py,sha256=uZ4-OSMja98toyraDaeG6OMjV7kU2hq-QsTjnDl-BfQ,1732
+check_scannability.py,sha256=IdHwzQtBWzx95zIDOx3B7OyzoKxTVtpn0wJUErFQRC0,5346
+extract_link_attributes.py,sha256=bfWC6h4QWj6YvwZ3-tc3K7oMC2wN4QdA4YMCKcYdKCg,3384
+find_unused_attributes.py,sha256=KYVhIgJobEtMzzVI4P7wkMym7Z6N27IdxQmg3qySvAo,4131
+format_asciidoc_spacing.py,sha256=B3Bo68_i_RJNlUdNLZ4TiYUslrbwhSkzX3Dyd9JWRo0,4080
+replace_link_attributes.py,sha256=OGD-COUG3JUCYOoARa32xqaSEcA-p31AJLk-d-FPUUQ,7492
+validate_links.py,sha256=KmN4dULwLiLM2lUyteXwbBuTuQHcNkCq0nhiaZ48BtI,6013
+doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
+doc_utils/extract_link_attributes.py,sha256=U0EvPZReJQigNfbT-icBsVT6Li64hYki5W7MQz6qqbc,22743
+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=gmAs68_njBqEz-Qni-UGgeYEDTMxlTWk_IOm76FONNE,7279
+doc_utils/scannability.py,sha256=XwlmHqDs69p_V36X7DLjPTy0DUoLszSGqYjJ9wE-3hg,982
+doc_utils/spinner.py,sha256=lJg15qzODiKoR0G6uFIk2BdVNgn9jFexoTRUMrjiWvk,3554
+doc_utils/topic_map_parser.py,sha256=tKcIO1m9r2K6dvPRGue58zqMr0O2zKU1gnZMzEE3U6o,4571
+doc_utils/unused_adoc.py,sha256=2cbqcYr1os2EhETUU928BlPRlsZVSdI00qaMhqjSIqQ,5263
+doc_utils/unused_attributes.py,sha256=EhbqPITy-f3PU8j2om5sUq0OtN1QwtyWD0G2TEx9rH8,6889
+doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,1456
+doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
+doc_utils/version_check.py,sha256=1ySC6Au21OqUMZr7AkIa3nMNh3M6wLQmPQCi-ZFIqoE,6338
+rolfedh_doc_utils-0.1.17.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.17.dist-info/METADATA,sha256=xj4KXU_A1ORuau9OuBst8DewvduJZ8rmdcBTEOKTXYw,7824
+rolfedh_doc_utils-0.1.17.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.17.dist-info/entry_points.txt,sha256=2J4Ojc3kkuArpe2xcUOPc0LxSWCmnctvw8hy8zpnbO4,418
+rolfedh_doc_utils-0.1.17.dist-info/top_level.txt,sha256=1w0JWD7w7gnM5Sga2K4fJieNZ7CHPTAf0ozYk5iIlmo,182
+rolfedh_doc_utils-0.1.17.dist-info/RECORD,,

validate_links.py

@@ -12,10 +12,13 @@ import argparse
 import sys
 import json
 from doc_utils.validate_links import LinkValidator, parse_transpositions, format_results
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.spinner import Spinner
 
 
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     """Main entry point for the validate-links CLI tool."""
     parser = argparse.ArgumentParser(
         description='Validate links in AsciiDoc documentation',

rolfedh_doc_utils-0.1.15.dist-info/RECORD

@@ -1,26 +0,0 @@
-archive_unused_files.py,sha256=h7CRwSPBVCOQs0hn_ASD4EXz8QJFcAO2x3KX9FVhXNM,1974
-archive_unused_images.py,sha256=4GSVPYkxqFoY-isy47P_1AhD1ziXgmajFiBGCtZ3olg,1564
-check_scannability.py,sha256=MvGLW4UGGcx-jZLsVRYXpXNAIEQyJZZnsN99zJzbtyc,5178
-extract_link_attributes.py,sha256=grPvVwOF9kqIOZ_uxYtJTkO3C2DNtIpKNPp6LlGK3Xs,3216
-find_unused_attributes.py,sha256=IUJKJr_MzxBXqg9rafUs9Kwi8AbU0x-H0AVflc1dhCU,3288
-format_asciidoc_spacing.py,sha256=_XpHqxYWm1AnZLUK_cDpfAJtsDCDF0b66m3opfYnIuU,3912
-replace_link_attributes.py,sha256=lJHrzIRJOmdt5WzCD0Lf-v9lOJDXBV7b75bOFZLNDPQ,7324
-validate_links.py,sha256=409fTAyBGTUrp6iSWuJ9AXExcdz8dC_4QeA_RvCIhus,5845
-doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
-doc_utils/extract_link_attributes.py,sha256=U0EvPZReJQigNfbT-icBsVT6Li64hYki5W7MQz6qqbc,22743
-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=gmAs68_njBqEz-Qni-UGgeYEDTMxlTWk_IOm76FONNE,7279
-doc_utils/scannability.py,sha256=XwlmHqDs69p_V36X7DLjPTy0DUoLszSGqYjJ9wE-3hg,982
-doc_utils/spinner.py,sha256=lJg15qzODiKoR0G6uFIk2BdVNgn9jFexoTRUMrjiWvk,3554
-doc_utils/topic_map_parser.py,sha256=tKcIO1m9r2K6dvPRGue58zqMr0O2zKU1gnZMzEE3U6o,4571
-doc_utils/unused_adoc.py,sha256=2cbqcYr1os2EhETUU928BlPRlsZVSdI00qaMhqjSIqQ,5263
-doc_utils/unused_attributes.py,sha256=EjTtWIKW_aXsR1JOgw5RSDVAqitJ_NfRMVOXVGaiWTY,5282
-doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,1456
-doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
-rolfedh_doc_utils-0.1.15.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.15.dist-info/METADATA,sha256=wUhG5aOP3eUggSenYO_D3bS8R4wCI7abvg1F7gWgR3E,7386
-rolfedh_doc_utils-0.1.15.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.15.dist-info/entry_points.txt,sha256=2J4Ojc3kkuArpe2xcUOPc0LxSWCmnctvw8hy8zpnbO4,418
-rolfedh_doc_utils-0.1.15.dist-info/top_level.txt,sha256=1w0JWD7w7gnM5Sga2K4fJieNZ7CHPTAf0ozYk5iIlmo,182
-rolfedh_doc_utils-0.1.15.dist-info/RECORD,,