rolfedh-doc-utils 0.1.0__py3-none-any.whl → 0.1.3__py3-none-any.whl

archive_unused_files.py

@@ -0,0 +1,35 @@
+"""
+Archive Unused AsciiDoc Files
+
+Scans './modules' and './assemblies' for AsciiDoc files not referenced by any other AsciiDoc file in the project. Optionally archives and deletes them.
+
+For full documentation and usage examples, see archive_unused_files.md in this directory.
+"""
+
+import argparse
+from doc_utils.unused_adoc import find_unused_adoc
+from doc_utils.file_utils import parse_exclude_list_file
+
+def main():
+    parser = argparse.ArgumentParser(description='Archive unused AsciiDoc 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).')
+    parser.add_argument('--exclude-file', action='append', default=[], help='File to exclude (can be used multiple times).')
+    parser.add_argument('--exclude-list', type=str, help='Path to a file containing directories or files to exclude, one per line.')
+    args = parser.parse_args()
+
+    scan_dirs = ['./modules', './modules/rn', './assemblies']
+    archive_dir = './archive'
+
+    exclude_dirs = list(args.exclude_dir)
+    exclude_files = list(args.exclude_file)
+    
+    if args.exclude_list:
+        list_dirs, list_files = parse_exclude_list_file(args.exclude_list)
+        exclude_dirs.extend(list_dirs)
+        exclude_files.extend(list_files)
+
+    find_unused_adoc(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files)
+
+if __name__ == '__main__':
+    main()

archive_unused_images.py

@@ -0,0 +1,35 @@
+"""
+Archive Unused Image Files
+
+Scans './modules' and './assemblies' for image files (e.g., .png, .jpg, .jpeg, .gif, .svg) not referenced by any AsciiDoc file in the project. Optionally archives and deletes them.
+
+For full documentation and usage examples, see archive_unused_files.md in this directory.
+"""
+
+import argparse
+from doc_utils.unused_images import find_unused_images
+from doc_utils.file_utils import parse_exclude_list_file
+
+def main():
+    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).')
+    parser.add_argument('--exclude-file', action='append', default=[], help='File to exclude (can be used multiple times).')
+    parser.add_argument('--exclude-list', type=str, help='Path to a file containing directories or files to exclude, one per line.')
+    args = parser.parse_args()
+
+    scan_dirs = ['.']
+    archive_dir = './archive'
+
+    exclude_dirs = list(args.exclude_dir)
+    exclude_files = list(args.exclude_file)
+    
+    if args.exclude_list:
+        list_dirs, list_files = parse_exclude_list_file(args.exclude_list)
+        exclude_dirs.extend(list_dirs)
+        exclude_files.extend(list_files)
+
+    find_unused_images(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files)
+
+if __name__ == '__main__':
+    main()

check_scannability.py

@@ -0,0 +1,109 @@
+"""
+Scannability Checker for AsciiDoc Files
+
+This script analyzes AsciiDoc (`.adoc`) files in the current directory to detect scannability issues that affect readability.
+
+- Flags sentences that exceed 22 words (default, adjustable with -s)
+- Flags paragraphs with more than 3 sentences (default, adjustable with -p)
+- Excludes code blocks (delimited by ----, ...., or [source] blocks) from analysis
+
+When using -o, the script prints the path to the report file; it does not attempt to open the file automatically. 
+
+For full documentation, see check_scannability.md in this directory.
+"""
+
+import os
+import sys
+import argparse
+from datetime import datetime
+from doc_utils.scannability import check_scannability
+from doc_utils.file_utils import collect_files, parse_exclude_list_file
+
+BASE_SENTENCE_WORD_LIMIT = 22
+BASE_PARAGRAPH_SENTENCE_LIMIT = 3
+
+def print_help():
+    print(__doc__)
+
+def main():
+    # Manual check for -h or --help to display the full docstring
+    if '-h' in sys.argv or '--help' in sys.argv:
+        print_help()
+        sys.exit(0)
+
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument('-s', '--max-sentence-length', type=int, default=0, help='Extra words allowed per sentence (default: 0, base: 22)')
+    parser.add_argument('-p', '--max-paragraph-sentences', type=int, default=0, help='Extra sentences allowed per paragraph (default: 0, base: 3)')
+    parser.add_argument('-v', '--verbose', action='store_true', help='Verbose output (show all files, even those without issues)')
+    parser.add_argument('-o', '--output', action='store_true', help='Output the report to a timestamped txt file in your home directory')
+    parser.add_argument('--exclude-dir', action='append', default=[], help='Directory to exclude (can be used multiple times).')
+    parser.add_argument('--exclude-file', action='append', default=[], help='File to exclude (can be used multiple times).')
+    parser.add_argument('--exclude-list', type=str, help='Path to a file containing directories or files to exclude, one per line.')
+    # Do not add -h/--help to argparse, handled manually above
+    args = parser.parse_args()
+
+    exclude_dirs = list(args.exclude_dir)
+    exclude_files = list(args.exclude_file)
+    
+    if args.exclude_list:
+        list_dirs, list_files = parse_exclude_list_file(args.exclude_list)
+        exclude_dirs.extend(list_dirs)
+        exclude_files.extend(list_files)
+    adoc_files = collect_files(['.'], {'.adoc'}, exclude_dirs, exclude_files)
+    sentence_word_limit = BASE_SENTENCE_WORD_LIMIT + args.max_sentence_length
+    paragraph_sentence_limit = BASE_PARAGRAPH_SENTENCE_LIMIT + args.max_paragraph_sentences
+    long_sentences, long_paragraphs = check_scannability(
+        adoc_files,
+        max_sentence_length=sentence_word_limit,
+        max_paragraph_sentences=paragraph_sentence_limit
+    )
+    # Build a report per file
+    report_lines = []
+    issues_by_file = {}
+    for file, line, sent in long_sentences:
+        issues_by_file.setdefault(file, []).append(f"Line {line}: Sentence exceeds {sentence_word_limit} words: {sent}")
+    for file, line, count in long_paragraphs:
+        issues_by_file.setdefault(file, []).append(f"Line {line}: Paragraph exceeds {paragraph_sentence_limit} sentences ({count} sentences)")
+    for adoc in adoc_files:
+        issues = issues_by_file.get(adoc, [])
+        if issues or args.verbose:
+            report_lines.append("")  # Blank line above each filename
+            report_lines.append(f"{adoc}:")
+            if issues:
+                for issue in issues:
+                    report_lines.append("  " + issue)
+            else:
+                report_lines.append("  No scannability issues found.")
+
+    output = "\n".join(report_lines)
+    if args.output:
+        timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
+        home_dir = os.path.expanduser("~")
+        filename = os.path.join(home_dir, f"{timestamp}.txt")
+        now_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        pwd = os.getcwd()
+        cmd = "python3 " + " ".join([sys.argv[0]] + sys.argv[1:])
+        metadata = [
+            "Scannability Report",
+            "",
+            f"Purpose: This report lists scannability issues in .adoc files in the current directory.",
+            f"Directory: {pwd}",
+            f"Date and Time: {now_str}",
+            f"Sentence length limit: {sentence_word_limit} words (22 plus -s/--max-sentence-length {args.max_sentence_length})",
+            f"Paragraph sentence limit: {paragraph_sentence_limit} sentences (3 plus -p/--max-paragraph-sentences {args.max_paragraph_sentences})",
+            "See check_scannability.md for usage instructions and examples.",
+            f"Command: {cmd}",
+            "",
+            "------------------------------------------------------------",
+            "",
+        ]
+        with open(filename, "w", encoding="utf-8") as f:
+            f.write("\n".join(metadata))
+            f.write(output.lstrip() + "\n")
+        print(f"Report written to: {filename}")
+    else:
+        if output:
+            print(output.lstrip())
+
+if __name__ == "__main__":
+    main()

doc_utils/file_utils.py

@@ -1,7 +1,6 @@
 # doc_utils/file_utils.py
 
 import os
-import re
 import zipfile
 from datetime import datetime
 
@@ -17,8 +16,26 @@ def collect_files(scan_dirs, extensions, exclude_dirs=None, exclude_files=None):
     for base_dir in scan_dirs:
         for root, dirs, files in os.walk(base_dir):
             abs_root = os.path.abspath(root)
-            # Exclude directories by absolute path
-            dirs[:] = [d for d in dirs if not os.path.islink(os.path.join(root, d)) and os.path.abspath(os.path.join(root, d)) not in exclude_dirs]
+            # Check if current root directory should be excluded
+            if abs_root in exclude_dirs:
+                dirs[:] = []  # Skip this directory entirely
+                continue
+            # Exclude directories by absolute path and check for any parent directory exclusions
+            new_dirs = []
+            for d in dirs:
+                dir_path = os.path.join(root, d)
+                abs_dir_path = os.path.abspath(dir_path)
+                if not os.path.islink(dir_path) and abs_dir_path not in exclude_dirs:
+                    # Also check if any parent of this directory is excluded
+                    excluded = False
+                    for exclude_dir in exclude_dirs:
+                        if abs_dir_path.startswith(exclude_dir + os.sep) or abs_dir_path == exclude_dir:
+                            excluded = True
+                            break
+                    if not excluded:
+                        new_dirs.append(d)
+            dirs[:] = new_dirs
+
             for f in files:
                 file_path = os.path.normpath(os.path.join(root, f))
                 abs_file_path = os.path.abspath(file_path)
@@ -31,6 +48,33 @@ def collect_files(scan_dirs, extensions, exclude_dirs=None, exclude_files=None):
     return list(dict.fromkeys(found_files))
 
 
+def parse_exclude_list_file(exclude_list_path):
+    """
+    Parse an exclusion list file and return lists of directories and files to exclude.
+    
+    Args:
+        exclude_list_path: Path to file containing paths to exclude (one per line)
+        
+    Returns:
+        tuple: (exclude_dirs, exclude_files) lists
+    """
+    exclude_dirs = []
+    exclude_files = []
+    
+    if exclude_list_path and os.path.exists(exclude_list_path):
+        with open(exclude_list_path, 'r', encoding='utf-8') as excl:
+            for line in excl:
+                line = line.strip()
+                if not line or line.startswith('#'):
+                    continue
+                if os.path.isdir(line):
+                    exclude_dirs.append(line)
+                else:
+                    exclude_files.append(line)
+    
+    return exclude_dirs, exclude_files
+
+
 def write_manifest_and_archive(unused_files, archive_dir, manifest_prefix, archive_prefix, archive=False):
     """
     Write a manifest of unused files and optionally archive and delete them.

doc_utils/topic_map_parser.py

@@ -0,0 +1,122 @@
+# doc_utils/topic_map_parser.py
+
+import os
+import yaml
+import glob
+
+def detect_repo_type(base_path='.'):
+    """
+    Detect whether the repository uses topic maps (OpenShift-docs style) 
+    or master.adoc files (traditional style).
+    
+    Returns:
+        'topic_map' - if _topic_maps directory with .yml files exists
+        'master_adoc' - if master.adoc files are found
+        'unknown' - if neither pattern is detected
+    """
+    topic_maps_dir = os.path.join(base_path, '_topic_maps')
+    
+    # Check for topic maps
+    if os.path.isdir(topic_maps_dir):
+        yml_files = glob.glob(os.path.join(topic_maps_dir, '*.yml'))
+        if yml_files:
+            return 'topic_map'
+    
+    # Check for master.adoc files
+    master_files = glob.glob(os.path.join(base_path, '**/master.adoc'), recursive=True)
+    if master_files:
+        return 'master_adoc'
+    
+    return 'unknown'
+
+
+def extract_files_from_topic_map(topic_map_path):
+    """
+    Extract all referenced .adoc files from a topic map YAML file.
+    
+    Returns a set of file paths referenced in the topic map.
+    """
+    referenced_files = set()
+    
+    try:
+        with open(topic_map_path, 'r', encoding='utf-8') as f:
+            # Use safe_load_all to handle multiple YAML documents
+            documents = yaml.safe_load_all(f)
+            
+            for doc in documents:
+                if doc is None:
+                    continue
+                    
+                # Process each topic group
+                process_topic_group(doc, referenced_files)
+                
+    except Exception as e:
+        print(f"Warning: Could not parse topic map {topic_map_path}: {e}")
+    
+    return referenced_files
+
+
+def process_topic_group(group, referenced_files, parent_dir=''):
+    """
+    Recursively process a topic group to extract all file references.
+    """
+    if not isinstance(group, dict):
+        return
+        
+    # Get the directory for this group
+    current_dir = group.get('Dir', '')
+    if parent_dir and current_dir:
+        current_dir = os.path.join(parent_dir, current_dir)
+    elif parent_dir:
+        current_dir = parent_dir
+        
+    # Process topics in this group
+    topics = group.get('Topics', [])
+    if isinstance(topics, list):
+        for topic in topics:
+            if isinstance(topic, dict):
+                # If topic has a File, add it
+                if 'File' in topic:
+                    file_path = topic['File']
+                    if current_dir:
+                        file_path = os.path.join(current_dir, file_path)
+                    # Add .adoc extension if not present
+                    if not file_path.endswith('.adoc'):
+                        file_path += '.adoc'
+                    referenced_files.add(file_path)
+                
+                # If topic has nested topics (sub-group), process recursively
+                if 'Topics' in topic:
+                    # For nested topics, use the Dir from the topic if present
+                    sub_dir = topic.get('Dir', '')
+                    if sub_dir:
+                        # If topic has its own Dir, append it to current_dir
+                        if current_dir:
+                            next_dir = os.path.join(current_dir, sub_dir)
+                        else:
+                            next_dir = sub_dir
+                    else:
+                        # If no Dir specified, keep current_dir
+                        next_dir = current_dir
+                    # Process only the Topics, not the whole topic dict
+                    process_topic_group({'Topics': topic['Topics']}, referenced_files, next_dir)
+
+
+def get_all_topic_map_references(base_path='.'):
+    """
+    Get all .adoc files referenced in all topic maps.
+    
+    Returns a set of all referenced file paths.
+    """
+    topic_maps_dir = os.path.join(base_path, '_topic_maps')
+    all_references = set()
+    
+    if not os.path.isdir(topic_maps_dir):
+        return all_references
+        
+    # Process all .yml files in _topic_maps
+    for yml_file in glob.glob(os.path.join(topic_maps_dir, '*.yml')):
+        references = extract_files_from_topic_map(yml_file)
+        all_references.update(references)
+    
+    return all_references

doc_utils/unused_adoc.py

@@ -3,22 +3,48 @@
 import os
 import re
 from .file_utils import collect_files, write_manifest_and_archive
+from .topic_map_parser import detect_repo_type, get_all_topic_map_references
 
 def find_unused_adoc(scan_dirs, archive_dir, archive=False, exclude_dirs=None, exclude_files=None):
+    # Detect repository type
+    repo_type = detect_repo_type()
+    print(f"Detected repository type: {repo_type}")
+    
+    # Collect all .adoc files in scan directories
     asciidoc_files = collect_files(scan_dirs, {'.adoc'}, exclude_dirs, exclude_files)
+    
+    # Track which files are referenced
+    referenced_files = set()
+    
+    if repo_type == 'topic_map':
+        # For OpenShift-docs style repos, get references from topic maps
+        topic_references = get_all_topic_map_references()
+        # Convert to basenames for comparison
+        referenced_files.update(os.path.basename(ref) for ref in topic_references)
+    
+    # Always scan for include:: directives in all .adoc files
     include_pattern = re.compile(r'include::(.+?)\[')
-    included_files = set()
     adoc_files = collect_files(['.'], {'.adoc'}, exclude_dirs, exclude_files)
+    
     for file_path in adoc_files:
         try:
             with open(file_path, 'r', encoding='utf-8') as f:
                 content = f.read()
                 includes = include_pattern.findall(content)
-                included_files.update(os.path.basename(include) for include in includes)
+                # Extract just the filename from the include path
+                for include in includes:
+                    # Handle both relative and absolute includes
+                    include_basename = os.path.basename(include)
+                    referenced_files.add(include_basename)
         except Exception as e:
             print(f"Warning: could not read {file_path}: {e}")
-    unused_files = [f for f in asciidoc_files if os.path.basename(f) not in included_files]
-    unused_files = list(dict.fromkeys(unused_files))
+    
+    # Find unused files by comparing basenames
+    unused_files = [f for f in asciidoc_files if os.path.basename(f) not in referenced_files]
+    unused_files = list(dict.fromkeys(unused_files))  # Remove duplicates
+    
+    print(f"Found {len(unused_files)} unused files out of {len(asciidoc_files)} total files in scan directories")
+    
     return write_manifest_and_archive(
         unused_files, archive_dir, 'to-archive', 'to-archive', archive=archive
     )

find_unused_attributes.py

@@ -0,0 +1,41 @@
+"""
+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}).
+
+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
+from datetime import datetime
+from doc_utils.unused_attributes import find_unused_attributes
+
+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('-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, '.')
+
+    lines = [f":{attr}:  NOT USED" for attr in unused]
+    output = '\n'.join(lines)
+
+    if output:
+        print('Unused attributes:')
+        print(output)
+    else:
+        print('All attributes are used.')
+
+    if args.output and output:
+        timestamp = datetime.now().strftime('%Y%m%d%H%M%S')
+        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(output + '\n')
+        print(f'Results written to: {filename}')
+
+if __name__ == '__main__':
+    main()

rolfedh_doc_utils-0.1.3.dist-info/METADATA

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: rolfedh-doc-utils
+Version: 0.1.3
+Summary: CLI tools for AsciiDoc documentation projects
+Author: Rolfe Dlugy-Hegwer
+License: MIT License
+        
+        Copyright (c) 2025 Rolfe Dlugy-Hegwer
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# doc-utils
+
+A set of Python utilities and CLI tools to help technical writers maintain AsciiDoc documentation repositories.
+
+> ⚠️ **IMPORTANT: Safety First**
+>
+> These tools can modify or delete files in your documentation repository. Always:
+> - **Work in a git branch** - Never run these tools on the main/master branch
+> - **Review all changes carefully** - Use `git diff` or a pull request to verify modifications
+> - **Check your preview builds** - Ensure no documentation errors were introduced
+
+## Resources
+
+- [PyPI: rolfedh-doc-utils](https://pypi.org/project/rolfedh-doc-utils/)
+- [GitHub repository](https://github.com/rolfedh/doc-utils)
+
+## Installation
+
+### From PyPI
+
+On modern Linux distributions, you may encounter an "externally-managed-environment" error. Use one of these methods:
+
+**Option 1: pipx (Recommended for CLI tools)**
+```sh
+pipx install rolfedh-doc-utils
+```
+
+**Option 2: pip with --user flag**
+```sh
+pip install --user rolfedh-doc-utils
+```
+
+**Option 3: Traditional pip (may require virtual environment)**
+```sh
+pip install rolfedh-doc-utils
+```
+
+### Upgrading
+
+To upgrade to the latest version:
+
+```sh
+# If installed with pipx:
+pipx upgrade rolfedh-doc-utils
+
+# If installed with pip:
+pip install --upgrade rolfedh-doc-utils  # or --user flag if needed
+```
+
+### For Development
+
+If you're developing or testing locally, install the package in editable mode:
+
+```sh
+# Clone the repository
+git clone https://github.com/rolfedh/doc-utils.git
+cd doc-utils
+
+# Install in editable mode
+pip install -e .
+```
+
+The following CLI tools are installed:
+
+* `check-scannability`
+* `archive-unused-files`
+* `archive-unused-images`
+* `find-unused-attributes`
+
+These tools can be run from any directory.
+
+### Add to PATH (if needed)
+
+By default, CLI tools install to:
+
+```sh
+$HOME/.local/bin
+```
+
+If this directory isn’t in your `PATH`, commands may not run. Append it to your shell configuration:
+
+```sh
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc
+```
+
+Then reload your shell:
+
+```sh
+source ~/.bashrc   # or ~/.zshrc
+```
+
+## CLI Tools Overview
+
+### `check-scannability`
+
+Scans `.adoc` files in the current directory to report:
+
+* Sentences that exceed a length limit (default: 22 words)
+* Paragraphs with too many sentences (default: 3 sentences)
+* Supports exclusion of files and directories
+
+➡️ See [`check_scannability.md`](https://github.com/rolfedh/doc-utils/blob/main/check_scannability.md) for details.
+
+---
+
+### `archive-unused-files`
+
+Scans the `./modules` and `./assemblies` directories for `.adoc` files that are not referenced. Optionally archives and deletes them.
+
+Works with both:
+- **OpenShift-docs style** repositories (uses `_topic_maps/*.yml` files)
+- **Traditional AsciiDoc** repositories (uses `master.adoc` files)
+
+➡️ See [`archive_unused_files.md`](https://github.com/rolfedh/doc-utils/blob/main/archive_unused_files.md).
+
+---
+
+### `archive-unused-images`
+
+Finds unused image files (e.g., `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`) in the current directory and optionally archives and deletes them.
+
+➡️ See [`archive_unused_images.md`](https://github.com/rolfedh/doc-utils/blob/main/archive_unused_images.md).
+
+---
+
+### `find-unused-attributes`
+
+Scans an attributes file (e.g., `attributes.adoc`) for unused attribute definitions across all `.adoc` files in the current directory.
+
+➡️ See [`find_unused_attributes.md`](https://github.com/rolfedh/doc-utils/blob/main/find_unused_attributes.md).
+
+## Best Practices for Safe Usage
+
+### Before Running Any Tool:
+
+- **Create a feature branch:**
+   ```sh
+   git checkout -b doc-cleanup-$(date +%Y%m%d)
+   ```
+
+- **Commit any pending changes:**
+   ```sh
+   git add -A && git commit -m "Save work before cleanup"
+   ```
+
+- **Run tools in preview mode first:**
+   - For archive tools: Run without `--archive` to see what would be affected
+
+- **Review all changes and preview builds**
+
+- **Only merge after verification:**
+
+## Usage
+
+To run the tools after installation:
+
+```sh
+check-scannability --help
+archive-unused-files --help
+find-unused-attributes attributes.adoc
+```
+
+Or run them directly from source:
+
+```sh
+python3 check_scannability.py
+python3 archive_unused_files.py
+python3 find_unused_attributes.py attributes.adoc
+```
+
+### Directory/File Exclusion
+
+All tools support excluding specific directories and files from scanning. You can use these options:
+
+1. **`--exclude-dir`** - Exclude specific directories (can be used multiple times):
+   ```sh
+   archive-unused-files --exclude-dir ./modules/temp --exclude-dir ./modules/old
+   ```
+
+2. **`--exclude-file`** - Exclude specific files (can be used multiple times):
+   ```sh
+   check-scannability --exclude-file ./README.adoc --exclude-file ./test.adoc
+   ```
+
+3. **`--exclude-list`** - Point to a text file containing exclusions:
+   ```sh
+   archive-unused-images --exclude-list .docutils-ignore
+   ```
+
+   The exclusion file format:
+   ```
+   # Comments are supported
+   ./modules/deprecated/
+   ./assemblies/archive/
+   ./images/temp/
+   specific-file.adoc
+   ```
+
+**Note:** When you exclude a parent directory, all its subdirectories are automatically excluded. Symbolic links are never followed during scanning.
+
+## Troubleshooting
+
+### ModuleNotFoundError
+
+If you see an error like `ModuleNotFoundError: No module named 'find_unused_attributes'`, this typically means:
+
+1. The package isn't installed. Run:
+   ```sh
+   pipx install rolfedh-doc-utils  # or pip install --user rolfedh-doc-utils
+   ```
+
+2. You're trying to run the script directly without installation. Either:
+   - Install the package first (see Installation section)
+   - Run the script using Python directly:
+     ```sh
+     python3 find_unused_attributes.py attributes.adoc
+     ```
+
+### Command not found
+
+If the command isn't found after installation, ensure `$HOME/.local/bin` is in your PATH (see "Add to PATH" section above).
+
+## Development
+
+### Running Tests
+
+The project includes a comprehensive test suite. To run tests:
+
+```sh
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Run all tests
+python -m pytest tests/
+
+# Run with verbose output
+python -m pytest tests/ -v
+```
+
+### Contributing
+
+Contributions are welcome! Please ensure:
+- All tests pass before submitting a PR
+- New features include appropriate tests
+- Code follows PEP 8 style guidelines
+- Documentation is updated as needed
+
+See [CONTRIBUTING.md](https://github.com/rolfedh/doc-utils/blob/main/CONTRIBUTING.md) for more details.
+
+## License
+
+This project is licensed under the terms of the [LICENSE](https://github.com/rolfedh/doc-utils/blob/main/LICENSE).

rolfedh_doc_utils-0.1.3.dist-info/RECORD

@@ -0,0 +1,17 @@
+archive_unused_files.py,sha256=MFdAtE8CDthida5H5FhvtEHZWrQAZZoAB-DQkTOc6gs,1537
+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
+doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
+doc_utils/file_utils.py,sha256=fpTh3xx759sF8sNocdn_arsP3KAv8XA6cTQTAVIZiZg,4247
+doc_utils/scannability.py,sha256=XwlmHqDs69p_V36X7DLjPTy0DUoLszSGqYjJ9wE-3hg,982
+doc_utils/topic_map_parser.py,sha256=4vmOPInoKAFO54qOz4EuK24hHTngI4GXzrw0D_QZzSc,4224
+doc_utils/unused_adoc.py,sha256=aPhq4KQG5VJGCg_cnqyhNWuADGEQA_dtjmvxtf7ylGA,2185
+doc_utils/unused_attributes.py,sha256=HBgmHelqearfWl3TTC2bZGiJytjLADIgiGQUNKqXXPg,1847
+doc_utils/unused_images.py,sha256=P9vcm00BidrLmxhjeczBtiFU-1wgfN5nCYdZjeCH1kM,1329
+rolfedh_doc_utils-0.1.3.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.3.dist-info/METADATA,sha256=nTGGOIULiuqFcveMw4kGsHF-NVbe-YK3sbElusT9ku0,8152
+rolfedh_doc_utils-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.3.dist-info/entry_points.txt,sha256=i8LqEsp0KD4YyVI_7wQ1TMgCuag32D7gQes6bLufmtM,216
+rolfedh_doc_utils-0.1.3.dist-info/top_level.txt,sha256=BkaYN3KbtNvLQjs-QGBKCJb5UAtjEbC_IqxSSIN9P-w,95
+rolfedh_doc_utils-0.1.3.dist-info/RECORD,,

rolfedh_doc_utils-0.1.3.dist-info/top_level.txt

@@ -0,0 +1,5 @@
+archive_unused_files
+archive_unused_images
+check_scannability
+doc_utils
+find_unused_attributes

rolfedh_doc_utils-0.1.0.dist-info/METADATA

@@ -1,83 +0,0 @@
-Metadata-Version: 2.4
-Name: rolfedh-doc-utils
-Version: 0.1.0
-Summary: CLI tools for AsciiDoc documentation projects
-Author: Rolfe Dlugy-Hegwer
-License: MIT License
-        
-        Copyright (c) 2025 Rolfe Dlugy-Hegwer
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# doc-utils
-
-This repository contains modular Python utilities and CLI scripts to help technical writers with documentation tasks.
-
-**Purpose:**
-Each script is now a thin CLI wrapper that delegates to reusable modules in the `doc_utils` package. For details on how to use a script, see the initial docstring, comments, or the corresponding Markdown help file.
-
-## Current Scripts
-
-- **check_scannability.py**  
-  Checks the scannability of AsciiDoc (`.adoc`) files in the current directory. Reports sentences that are too long and paragraphs that contain too many sentences, based on configurable limits. See [check_scannability.md](check_scannability.md) for usage and examples.
-
-- **archive_unused_files.py**  
-  Scans `./modules` and `./assemblies` for AsciiDoc files not referenced by any other AsciiDoc file in the project. Optionally archives and deletes them. See [archive_unused_files.md](archive_unused_files.md) for usage and examples.
-
-- **archive_unused_images.py**  
-  Scans all directories for image files (e.g., `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`) not referenced by any AsciiDoc file in the project. Optionally archives and deletes them. See [archive_unused_images.md](archive_unused_images.md) for usage and examples.
-
-- **find_unused_attributes.py**  
-  Scans a user-specified attributes file (e.g., `attributes.adoc`) for attribute definitions (e.g., `:version:`) and recursively scans all `.adoc` files in the current directory for usages (e.g., `{version}`). Reports any attribute that is defined but not used in any `.adoc` file as **NOT USED** in both the command line output and a timestamped output file. See [find_unused_attributes.md](find_unused_attributes.md) for usage and examples.
-
-## Modular Python Package
-
-The core logic for all scripts is implemented in the `doc_utils/` package. You can import and reuse these utilities in your own scripts or tests:
-
-- `doc_utils.file_utils` — file collection, manifest, and archiving utilities
-- `doc_utils.unused_images` — logic for finding and archiving unused images
-- `doc_utils.unused_adoc` — logic for finding and archiving unused AsciiDoc files
-- `doc_utils.scannability` — logic for checking AsciiDoc scannability
-- `doc_utils.unused_attributes` — logic for finding unused AsciiDoc attributes
-
-## How to Use
-
-1. Open the script you are interested in (for example, `check_scannability.py` or `find_unused_attributes.py`).
-2. Read the top of the script or the corresponding `.md` file for instructions, options, and examples.
-3. Run the script from your terminal as described in the usage section.
-
-## Running Tests
-
-To run all tests, install the development requirements and run pytest from the project root:
-
-```sh
-pip install -r requirements-dev.txt
-pytest
-```
-
-All tests and fixtures are located in the `tests/` directory. See `tests/README.md` for details.
-
----
-
-*For licensing information, see [LICENSE](LICENSE).*

rolfedh_doc_utils-0.1.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
-doc_utils/file_utils.py,sha256=ftX4XN4tD2kLPkJzKDXsJUZLBq2R2hTDkK08FqNNqlU,2606
-doc_utils/scannability.py,sha256=XwlmHqDs69p_V36X7DLjPTy0DUoLszSGqYjJ9wE-3hg,982
-doc_utils/unused_adoc.py,sha256=gvP1eClEbVebN2jXA41-bPnbVhYz6JHEIbGZCg8JD0s,1115
-doc_utils/unused_attributes.py,sha256=HBgmHelqearfWl3TTC2bZGiJytjLADIgiGQUNKqXXPg,1847
-doc_utils/unused_images.py,sha256=P9vcm00BidrLmxhjeczBtiFU-1wgfN5nCYdZjeCH1kM,1329
-rolfedh_doc_utils-0.1.0.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.0.dist-info/METADATA,sha256=NpSNWXDb4TmGY3rOMOPM-85jF74BLllx4e5mrsmvwQk,4417
-rolfedh_doc_utils-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.0.dist-info/entry_points.txt,sha256=i8LqEsp0KD4YyVI_7wQ1TMgCuag32D7gQes6bLufmtM,216
-rolfedh_doc_utils-0.1.0.dist-info/top_level.txt,sha256=KeCjW0XQZ4Qx_nIFjNLhIqrL5_mxHhGxSwsZglGWKDk,10
-rolfedh_doc_utils-0.1.0.dist-info/RECORD,,

rolfedh_doc_utils-0.1.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-doc_utils