rolfedh-doc-utils 0.1.35__py3-none-any.whl → 0.1.38__py3-none-any.whl

doc_utils/missing_source_directive.py

@@ -0,0 +1,211 @@
+# doc_utils/missing_source_directive.py
+
+"""
+Detects code blocks (----) that are missing [source] directive on the preceding line.
+
+This module provides functionality to scan AsciiDoc files for code blocks that lack
+proper source directives, which can cause issues with AsciiDoc-to-DocBook XML conversion.
+"""
+
+import os
+import re
+
+def is_code_block_start(line):
+    """Check if line is a code block delimiter (4 or more dashes)"""
+    return re.match(r'^-{4,}$', line.strip())
+
+def has_source_directive(line):
+    """Check if line contains [source] directive"""
+    # Match [source], [source,lang], [source, lang], etc.
+    return re.match(r'^\[source[\s,]', line.strip())
+
+def is_empty_or_whitespace(line):
+    """Check if line is empty or contains only whitespace"""
+    return len(line.strip()) == 0
+
+def scan_file(filepath):
+    """
+    Scan a single AsciiDoc file for missing [source] directives.
+
+    Args:
+        filepath: Path to the AsciiDoc file to scan
+
+    Returns:
+        List of issue dictionaries containing line_num, prev_line_num, and prev_line
+    """
+    issues = []
+
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+
+        in_code_block = False
+
+        for i, line in enumerate(lines, start=1):
+            # Check if current line is a code block delimiter
+            if is_code_block_start(line):
+                if not in_code_block:
+                    # This is the START of a code block
+                    prev_line_num = i - 1
+                    prev_line = lines[prev_line_num - 1].rstrip() if prev_line_num > 0 else ""
+
+                    # Check if [source] exists in previous lines (within last 3 lines)
+                    # This handles cases where there's a title between [source] and ----
+                    has_source_in_context = False
+                    for lookback in range(1, min(4, i)):
+                        check_line = lines[i - lookback - 1].strip()
+                        if has_source_directive(check_line):
+                            has_source_in_context = True
+                            break
+                        # Stop looking if we hit an empty line or structural element
+                        if not check_line or check_line.startswith(('=', '----')):
+                            break
+
+                    # Only flag if:
+                    # 1. No [source] directive in recent context
+                    # 2. Previous line is not empty (which might be valid formatting)
+                    if (not has_source_in_context and
+                        not is_empty_or_whitespace(prev_line)):
+
+                        # Additional heuristic: check if previous line looks like it should have [source]
+                        # Skip if previous line is a title, comment, or other structural element
+                        prev_stripped = prev_line.strip()
+
+                        # Skip common valid patterns
+                        if prev_stripped.startswith(('=', '//', 'NOTE:', 'TIP:', 'WARNING:', 'IMPORTANT:', 'CAUTION:')):
+                            in_code_block = True
+                            continue
+
+                        # Skip if previous line is already an attribute block (but not [source])
+                        if prev_stripped.startswith('[') and prev_stripped.endswith(']'):
+                            # It's some other attribute like [id], [role], etc., might be intentional
+                            in_code_block = True
+                            continue
+
+                        # Skip if previous line is just a plus sign (continuation)
+                        if prev_stripped == '+':
+                            in_code_block = True
+                            continue
+
+                        # Skip if previous line is a block title (starts with .)
+                        if prev_stripped.startswith('.') and len(prev_stripped) > 1:
+                            # This might be a title for a source block that's defined earlier
+                            # Check if there's a [source] before the title
+                            if i >= 3:
+                                two_lines_back = lines[i - 3].strip()
+                                if has_source_directive(two_lines_back):
+                                    in_code_block = True
+                                    continue
+
+                        issues.append({
+                            'line_num': i,
+                            'prev_line_num': prev_line_num,
+                            'prev_line': prev_line[:80]  # Truncate for display
+                        })
+
+                    in_code_block = True
+                else:
+                    # This is the END of a code block
+                    in_code_block = False
+
+    except Exception as e:
+        raise IOError(f"Error reading {filepath}: {e}")
+
+    return issues
+
+def fix_file(filepath, issues):
+    """
+    Insert [source] directives for missing code blocks.
+
+    Args:
+        filepath: Path to the AsciiDoc file to fix
+        issues: List of issue dictionaries from scan_file()
+
+    Returns:
+        True if successful, False otherwise
+    """
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+
+        # Sort issues by line number in reverse order so we can insert from bottom to top
+        # This prevents line number shifts from affecting subsequent insertions
+        sorted_issues = sorted(issues, key=lambda x: x['line_num'], reverse=True)
+
+        for issue in sorted_issues:
+            line_num = issue['line_num']
+            # Insert [source] directive before the ---- line (at line_num - 1, which is index line_num - 1)
+            insert_index = line_num - 1
+            lines.insert(insert_index, '[source]\n')
+
+        # Write the modified content back to the file
+        with open(filepath, 'w', encoding='utf-8') as f:
+            f.writelines(lines)
+
+        return True
+
+    except Exception as e:
+        raise IOError(f"Error fixing {filepath}: {e}")
+
+def find_missing_source_directives(scan_dir='.', auto_fix=False):
+    """
+    Scan directory for AsciiDoc files with missing [source] directives.
+
+    Args:
+        scan_dir: Directory to scan (default: current directory)
+        auto_fix: If True, automatically insert [source] directives
+
+    Returns:
+        Dictionary with statistics:
+        - total_issues: Total number of issues found
+        - files_with_issues: Number of files with issues
+        - files_fixed: Number of files successfully fixed (if auto_fix=True)
+        - file_details: List of dictionaries with file paths and their issues
+    """
+    if not os.path.isdir(scan_dir):
+        raise ValueError(f"Directory '{scan_dir}' does not exist")
+
+    total_issues = 0
+    files_with_issues = 0
+    files_fixed = 0
+    file_details = []
+
+    # Find all .adoc files (excluding symbolic links)
+    adoc_files = []
+    for root, dirs, files in os.walk(scan_dir):
+        for filename in files:
+            if filename.endswith('.adoc'):
+                filepath = os.path.join(root, filename)
+                # Skip symbolic links
+                if not os.path.islink(filepath):
+                    adoc_files.append(filepath)
+
+    for filepath in sorted(adoc_files):
+        issues = scan_file(filepath)
+
+        if issues:
+            files_with_issues += 1
+            total_issues += len(issues)
+
+            file_info = {
+                'filepath': filepath,
+                'issues': issues,
+                'fixed': False
+            }
+
+            if auto_fix:
+                try:
+                    if fix_file(filepath, issues):
+                        files_fixed += 1
+                        file_info['fixed'] = True
+                except Exception as e:
+                    file_info['error'] = str(e)
+
+            file_details.append(file_info)
+
+    return {
+        'total_issues': total_issues,
+        'files_with_issues': files_with_issues,
+        'files_fixed': files_fixed,
+        'file_details': file_details
+    }

doc_utils/version.py

@@ -1,7 +1,7 @@
 """Version information for doc-utils."""
 
 # This should match the version in pyproject.toml
-__version__ = "0.1.35"
+__version__ = "0.1.37"
 
 def get_version():
     """Return the current version string."""

{rolfedh_doc_utils-0.1.35.dist-info → rolfedh_doc_utils-0.1.38.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.35
+Version: 0.1.38
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -94,7 +94,8 @@ doc-utils --version  # Show version
 
 | Tool | Description | Usage |
 |------|-------------|-------|
-| **`validate-links`** | Validates all links in documentation, with URL transposition for preview environments | `validate-links --transpose "https://prod--https://preview"` |
+| **`validate-links`** | Validates links in AsciiDoc source files, with URL transposition for preview environments | `validate-links --transpose "https://prod--https://preview"` |
+| **`check-published-links`** | Validates links on published HTML docs using linkchecker, with URL rewriting for misresolved paths | `check-published-links https://docs.example.com/guide/` |
 | **`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`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run modules/` |

{rolfedh_doc_utils-0.1.35.dist-info → rolfedh_doc_utils-0.1.38.dist-info}/RECORD

@@ -1,8 +1,11 @@
 archive_unused_files.py,sha256=YKYPtuBHEZcsyQSwSYxSYvw9v9Mh6Of8MqT53A5bM44,2438
 archive_unused_images.py,sha256=EvPhMIwp6_AHKtuNYQ663q6biXBeXaqf88NzWrhvtIE,2029
+check_published_links.py,sha256=nk07prV6xHVqVrYCy2Eb8BWkjkgJBhczk8U0E-KeIvA,43258
 check_scannability.py,sha256=O6ROr-e624jVPvPpASpsWo0gTfuCFpA2mTSX61BjAEI,5478
+check_source_directives.py,sha256=JiIvn_ph9VKPMH4zg-aSsuIGQZcnI_imj7rZLLE04L8,3660
 convert_callouts_interactive.py,sha256=4PjiVIOWxNJiJLQuBHT3x6rE46-hgfFHSaoo5quYIs8,22889
 convert_callouts_to_deflist.py,sha256=BoqW5_GkQ-KqNzn4vmE6lsQosrPV0lkB-bfAx3dzyMw,25886
+convert_tables_to_deflists.py,sha256=PIP6xummuMqC3aSzahKKRBYahes_j5ZpHp_-k6BjurY,15599
 doc_utils_cli.py,sha256=J3CE7cTDDCRGkhAknYejNWHhk5t9YFGt27WDVfR98Xk,5111
 extract_link_attributes.py,sha256=wR2SmR2la-jR6DzDbas2PoNONgRZ4dZ6aqwzkwEv8Gs,3516
 find_unused_attributes.py,sha256=77CxFdm72wj6SO81w-auMdDjnvF83jWy_qaM7DsAtBw,4263
@@ -19,6 +22,7 @@ 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=RL2WU_dG_UfGL01LnevcyJfKsvYy_ogNyeoVX-Fyqks,13579
+doc_utils/missing_source_directive.py,sha256=X3Acn0QJTk6XjmBXhGus5JAjlIitCiicCRE3fslifyw,8048
 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
@@ -27,12 +31,12 @@ doc_utils/unused_adoc.py,sha256=LPQWPGEOizXECxepk7E_5cjTVvKn6RXQYTWG97Ps5VQ,9077
 doc_utils/unused_attributes.py,sha256=OHyAdaBD7aNo357B0SLBN5NC_jNY5TWXMwgtfJNh3X8,7621
 doc_utils/unused_images.py,sha256=hL8Qrik9QCkVh54eBLuNczRS9tMnsqIEfavNamM1UeQ,5664
 doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
-doc_utils/version.py,sha256=rh_oI-y8ZbMOpFC_a1Qkwb1Tq4FPWdm-vTVRUBqtHGU,203
+doc_utils/version.py,sha256=zVnktTYITGhLqPNoyXbSnWi5bQassZ3M9S4LgDCGD-E,203
 doc_utils/version_check.py,sha256=-31Y6AN0KGi_CUCAVOOhf6bPO3r7SQIXPxxeffLAF0w,7535
 doc_utils/warnings_report.py,sha256=20yfwqBjOprfFhQwCujbcsvjJCbHHhmH84uAujm-y-o,8877
-rolfedh_doc_utils-0.1.35.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.35.dist-info/METADATA,sha256=hsWjS4apZYXM4Qk38o3KOhMBEaqe55gc9e5QGZqAYEc,8325
-rolfedh_doc_utils-0.1.35.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.35.dist-info/entry_points.txt,sha256=vL_LlLKOiurRzchrq8iRUQG19Xi9lSAFVZGjO-xyErk,577
-rolfedh_doc_utils-0.1.35.dist-info/top_level.txt,sha256=J4xtr3zoyCip27b3GnticFVZoyz5HHtgGqHQ-SZONCA,265
-rolfedh_doc_utils-0.1.35.dist-info/RECORD,,
+rolfedh_doc_utils-0.1.38.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.38.dist-info/METADATA,sha256=gkxP50nyURTB-KhxNcT9rlDP77xVOXaRts6F1J6Dvus,8520
+rolfedh_doc_utils-0.1.38.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.38.dist-info/entry_points.txt,sha256=SpOivexG_Bx1MWn4yC1UUXhttcXqZG851kejOAa3RFQ,744
+rolfedh_doc_utils-0.1.38.dist-info/top_level.txt,sha256=FdhF5liH3KqypcFiLU-3GJdXJTIGwJO_UBAcOnC1yTo,338
+rolfedh_doc_utils-0.1.38.dist-info/RECORD,,

{rolfedh_doc_utils-0.1.35.dist-info → rolfedh_doc_utils-0.1.38.dist-info}/entry_points.txt

@@ -1,9 +1,12 @@
 [console_scripts]
 archive-unused-files = archive_unused_files:main
 archive-unused-images = archive_unused_images:main
+check-published-links = check_published_links:main
 check-scannability = check_scannability:main
+check-source-directives = check_source_directives:main
 convert-callouts-interactive = convert_callouts_interactive:main
 convert-callouts-to-deflist = convert_callouts_to_deflist:main
+convert-tables-to-deflists = convert_tables_to_deflists:main
 doc-utils = doc_utils_cli:main
 extract-link-attributes = extract_link_attributes:main
 find-unused-attributes = find_unused_attributes:main

{rolfedh_doc_utils-0.1.35.dist-info → rolfedh_doc_utils-0.1.38.dist-info}/top_level.txt

@@ -1,9 +1,12 @@
 archive_unused_files
 archive_unused_images
 callout_lib
+check_published_links
 check_scannability
+check_source_directives
 convert_callouts_interactive
 convert_callouts_to_deflist
+convert_tables_to_deflists
 doc_utils
 doc_utils_cli
 extract_link_attributes