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

doc_utils/__init__.py

@@ -0,0 +1,3 @@
+# doc_utils/__init__.py
+
+# This file marks doc_utils as a Python package.

doc_utils/file_utils.py

@@ -0,0 +1,60 @@
+# doc_utils/file_utils.py
+
+import os
+import re
+import zipfile
+from datetime import datetime
+
+
+def collect_files(scan_dirs, extensions, exclude_dirs=None, exclude_files=None):
+    """
+    Recursively collect files with given extensions from scan_dirs, excluding symlinks, exclude_dirs, and exclude_files.
+    Returns a list of normalized file paths.
+    """
+    exclude_dirs = set(os.path.abspath(os.path.normpath(d)) for d in (exclude_dirs or []))
+    exclude_files = set(os.path.abspath(os.path.normpath(f)) for f in (exclude_files or []))
+    found_files = []
+    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]
+            for f in files:
+                file_path = os.path.normpath(os.path.join(root, f))
+                abs_file_path = os.path.abspath(file_path)
+                if os.path.islink(file_path):
+                    continue
+                if abs_file_path in exclude_files:
+                    continue
+                if os.path.splitext(f)[1].lower() in extensions:
+                    found_files.append(file_path)
+    return list(dict.fromkeys(found_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.
+    Returns the manifest path and (if archive=True) the archive path.
+    """
+    if not unused_files:
+        print("No unused files found. No manifest or ZIP archive created.")
+        return None, None
+    now = datetime.now()
+    datetime_str = now.strftime('%Y-%m-%d_%H%M%S')
+    output_file = f'{manifest_prefix}-{datetime_str}.txt'
+    os.makedirs(archive_dir, exist_ok=True)
+    manifest_path = os.path.join(archive_dir, output_file)
+    with open(manifest_path, 'w') as f:
+        for file in unused_files:
+            print(file)
+            f.write(file + '\n')
+    archive_path = None
+    if archive:
+        archive_path = os.path.join(archive_dir, f"{archive_prefix}-{datetime_str}.zip")
+        with zipfile.ZipFile(archive_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            for file in unused_files:
+                arcname = os.path.relpath(file)
+                print(f"Archiving: {file} -> {archive_path} ({arcname})")
+                zipf.write(file, arcname)
+                os.remove(file)
+    return manifest_path, archive_path

doc_utils/scannability.py

@@ -0,0 +1,23 @@
+# doc_utils/scannability.py
+
+import os
+import re
+
+def check_scannability(adoc_files, max_sentence_length=22, max_paragraph_sentences=3):
+    long_sentences = []
+    long_paragraphs = []
+    for file_path in adoc_files:
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+                paragraphs = content.split('\n\n')
+                for i, para in enumerate(paragraphs):
+                    sentences = re.split(r'(?<=[.!?]) +', para.strip())
+                    for sent in sentences:
+                        if len(sent.split()) > max_sentence_length:
+                            long_sentences.append((file_path, i+1, sent.strip()))
+                    if len(sentences) > max_paragraph_sentences:
+                        long_paragraphs.append((file_path, i+1, len(sentences)))
+        except Exception as e:
+            print(f"Warning: could not read {file_path}: {e}")
+    return long_sentences, long_paragraphs

doc_utils/unused_adoc.py

@@ -0,0 +1,24 @@
+# doc_utils/unused_adoc.py
+
+import os
+import re
+from .file_utils import collect_files, write_manifest_and_archive
+
+def find_unused_adoc(scan_dirs, archive_dir, archive=False, exclude_dirs=None, exclude_files=None):
+    asciidoc_files = collect_files(scan_dirs, {'.adoc'}, exclude_dirs, exclude_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)
+        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))
+    return write_manifest_and_archive(
+        unused_files, archive_dir, 'to-archive', 'to-archive', archive=archive
+    )

doc_utils/unused_attributes.py

@@ -0,0 +1,50 @@
+"""
+Module for finding unused AsciiDoc attributes.
+
+Functions:
+- parse_attributes_file: Parse attribute names from an attributes.adoc file.
+- find_adoc_files: Recursively find all .adoc files in a directory (ignoring symlinks).
+- scan_for_attribute_usage: Find which attributes are used in a set of .adoc files.
+- find_unused_attributes: Main function to return unused attributes.
+"""
+
+import os
+import re
+from typing import Set, List
+
+def parse_attributes_file(attr_file: str) -> Set[str]:
+    attributes = set()
+    with open(attr_file, 'r', encoding='utf-8') as f:
+        for line in f:
+            match = re.match(r'^:([\w-]+):', line.strip())
+            if match:
+                attributes.add(match.group(1))
+    return attributes
+
+def find_adoc_files(root_dir: str) -> List[str]:
+    adoc_files = []
+    for dirpath, dirnames, filenames in os.walk(root_dir, followlinks=False):
+        for fname in filenames:
+            if fname.endswith('.adoc'):
+                full_path = os.path.join(dirpath, fname)
+                if not os.path.islink(full_path):
+                    adoc_files.append(full_path)
+    return adoc_files
+
+def scan_for_attribute_usage(adoc_files: List[str], attributes: Set[str]) -> Set[str]:
+    used = set()
+    attr_pattern = re.compile(r'\{([\w-]+)\}')
+    for file in adoc_files:
+        with open(file, 'r', encoding='utf-8') as f:
+            for line in f:
+                for match in attr_pattern.findall(line):
+                    if match in attributes:
+                        used.add(match)
+    return used
+
+def find_unused_attributes(attr_file: str, adoc_root: str = '.') -> List[str]:
+    attributes = parse_attributes_file(attr_file)
+    adoc_files = find_adoc_files(adoc_root)
+    used = scan_for_attribute_usage(adoc_files, attributes)
+    unused = sorted(attributes - used)
+    return unused

doc_utils/unused_images.py

@@ -0,0 +1,28 @@
+# doc_utils/unused_images.py
+
+import os
+import re
+from .file_utils import collect_files, write_manifest_and_archive
+
+IMAGE_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.gif', '.svg'}
+
+def find_unused_images(scan_dirs, archive_dir, archive=False, exclude_dirs=None, exclude_files=None):
+    image_files = collect_files(scan_dirs, IMAGE_EXTENSIONS, exclude_dirs, exclude_files)
+    adoc_files = collect_files(['.'], {'.adoc'}, exclude_dirs, exclude_files)
+    referenced_images = set()
+    image_ref_pattern = re.compile(r'(?i)image::([^\[]+)[\[]|image:([^\[]+)[\[]|"([^"\s]+\.(?:png|jpg|jpeg|gif|svg))"')
+    for adoc_file in adoc_files:
+        try:
+            with open(adoc_file, 'r', encoding='utf-8') as f:
+                content = f.read()
+                for match in image_ref_pattern.findall(content):
+                    for group in match:
+                        if group:
+                            referenced_images.add(os.path.basename(group))
+        except Exception as e:
+            print(f"Warning: could not read {adoc_file}: {e}")
+    unused_images = [f for f in image_files if os.path.basename(f) not in referenced_images]
+    unused_images = list(dict.fromkeys(unused_images))
+    return write_manifest_and_archive(
+        unused_images, archive_dir, 'unused-images', 'unused-images', archive=archive
+    )

rolfedh_doc_utils-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+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

@@ -0,0 +1,12 @@
+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/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rolfedh_doc_utils-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+archive-unused-files = archive_unused_files:main
+archive-unused-images = archive_unused_images:main
+check-scannability = check_scannability:main
+find-unused-attributes = find_unused_attributes:main

rolfedh_doc_utils-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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.

rolfedh_doc_utils-0.1.0.dist-info/top_level.txt

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