rolfedh-doc-utils 0.1.2__tar.gz → 0.1.3__tar.gz

{rolfedh_doc_utils-0.1.2/rolfedh_doc_utils.egg-info → rolfedh_doc_utils-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.2
+Version: 0.1.3
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -28,6 +28,7 @@ License: MIT License
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
 Dynamic: license-file
 
 # doc-utils
@@ -50,11 +51,34 @@ A set of Python utilities and CLI tools to help technical writers maintain Ascii
 
 ### From PyPI
 
-Install the package 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
 
@@ -116,6 +140,10 @@ Scans `.adoc` files in the current directory to report:
 
 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).
 
 ---
@@ -211,7 +239,7 @@ If you see an error like `ModuleNotFoundError: No module named 'find_unused_attr
 
 1. The package isn't installed. Run:
    ```sh
-   pip install rolfedh-doc-utils
+   pipx install rolfedh-doc-utils  # or pip install --user rolfedh-doc-utils
    ```
 
 2. You're trying to run the script directly without installation. Either:

{rolfedh_doc_utils-0.1.2 → rolfedh_doc_utils-0.1.3}/README.md

@@ -18,11 +18,34 @@ A set of Python utilities and CLI tools to help technical writers maintain Ascii
 
 ### From PyPI
 
-Install the package 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
 
@@ -84,6 +107,10 @@ Scans `.adoc` files in the current directory to report:
 
 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).
 
 ---
@@ -179,7 +206,7 @@ If you see an error like `ModuleNotFoundError: No module named 'find_unused_attr
 
 1. The package isn't installed. Run:
    ```sh
-   pip install rolfedh-doc-utils
+   pipx install rolfedh-doc-utils  # or pip install --user rolfedh-doc-utils
    ```
 
 2. You're trying to run the script directly without installation. Either:

rolfedh_doc_utils-0.1.3/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

rolfedh_doc_utils-0.1.3/doc_utils/unused_adoc.py

@@ -0,0 +1,50 @@
+# doc_utils/unused_adoc.py
+
+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::(.+?)\[')
+    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)
+                # 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}")
+    
+    # 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
+    )

{rolfedh_doc_utils-0.1.2 → rolfedh_doc_utils-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rolfedh-doc-utils"
-version = "0.1.2"
+version = "0.1.3"
 description = "CLI tools for AsciiDoc documentation projects"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -12,7 +12,7 @@ license = { file = "LICENSE" }
 authors = [
   { name="Rolfe Dlugy-Hegwer" }
 ]
-dependencies = []
+dependencies = ["PyYAML>=6.0"]
 
 [project.scripts]
 check-scannability = "check_scannability:main"

{rolfedh_doc_utils-0.1.2 → rolfedh_doc_utils-0.1.3/rolfedh_doc_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.2
+Version: 0.1.3
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -28,6 +28,7 @@ License: MIT License
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
 Dynamic: license-file
 
 # doc-utils
@@ -50,11 +51,34 @@ A set of Python utilities and CLI tools to help technical writers maintain Ascii
 
 ### From PyPI
 
-Install the package 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
 
@@ -116,6 +140,10 @@ Scans `.adoc` files in the current directory to report:
 
 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).
 
 ---
@@ -211,7 +239,7 @@ If you see an error like `ModuleNotFoundError: No module named 'find_unused_attr
 
 1. The package isn't installed. Run:
    ```sh
-   pip install rolfedh-doc-utils
+   pipx install rolfedh-doc-utils  # or pip install --user rolfedh-doc-utils
    ```
 
 2. You're trying to run the script directly without installation. Either:

{rolfedh_doc_utils-0.1.2 → rolfedh_doc_utils-0.1.3}/rolfedh_doc_utils.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ pyproject.toml
 doc_utils/__init__.py
 doc_utils/file_utils.py
 doc_utils/scannability.py
+doc_utils/topic_map_parser.py
 doc_utils/unused_adoc.py
 doc_utils/unused_attributes.py
 doc_utils/unused_images.py
@@ -15,6 +16,7 @@ rolfedh_doc_utils.egg-info/PKG-INFO
 rolfedh_doc_utils.egg-info/SOURCES.txt
 rolfedh_doc_utils.egg-info/dependency_links.txt
 rolfedh_doc_utils.egg-info/entry_points.txt
+rolfedh_doc_utils.egg-info/requires.txt
 rolfedh_doc_utils.egg-info/top_level.txt
 tests/test_archive_unused_files.py
 tests/test_archive_unused_images.py
@@ -25,4 +27,5 @@ tests/test_fixture_archive_unused_files.py
 tests/test_fixture_archive_unused_images.py
 tests/test_fixture_check_scannability.py
 tests/test_parse_exclude_list.py
+tests/test_topic_map_parser.py
 tests/test_unused_attributes.py

rolfedh_doc_utils-0.1.3/rolfedh_doc_utils.egg-info/requires.txt

@@ -0,0 +1 @@
+PyYAML>=6.0

rolfedh_doc_utils-0.1.3/tests/test_topic_map_parser.py

@@ -0,0 +1,190 @@
+import pytest
+import os
+import tempfile
+import yaml
+from doc_utils.topic_map_parser import (
+    detect_repo_type, 
+    extract_files_from_topic_map,
+    process_topic_group,
+    get_all_topic_map_references
+)
+
+
+class TestDetectRepoType:
+    def test_detect_topic_map_repo(self):
+        """Test detection of OpenShift-docs style repository with topic maps."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Create _topic_maps directory with a .yml file
+            topic_maps_dir = os.path.join(tmpdir, '_topic_maps')
+            os.makedirs(topic_maps_dir)
+            
+            # Create a sample topic map file
+            topic_map_file = os.path.join(topic_maps_dir, '_topic_map.yml')
+            with open(topic_map_file, 'w') as f:
+                f.write("---\nName: Test\nDir: test\n")
+            
+            assert detect_repo_type(tmpdir) == 'topic_map'
+    
+    def test_detect_master_adoc_repo(self):
+        """Test detection of traditional repository with master.adoc files."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Create a master.adoc file
+            master_file = os.path.join(tmpdir, 'master.adoc')
+            with open(master_file, 'w') as f:
+                f.write("= Master Document\n")
+            
+            assert detect_repo_type(tmpdir) == 'master_adoc'
+    
+    def test_detect_unknown_repo(self):
+        """Test detection returns 'unknown' for unrecognized repository structure."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Empty directory
+            assert detect_repo_type(tmpdir) == 'unknown'
+
+
+class TestExtractFilesFromTopicMap:
+    def test_extract_simple_topic_map(self):
+        """Test extracting files from a simple topic map."""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.yml', delete=False) as f:
+            f.write("""---
+Name: Overview
+Dir: welcome
+Topics:
+- Name: Welcome
+  File: index
+- Name: Introduction
+  File: intro
+""")
+            f.flush()
+            
+            try:
+                files = extract_files_from_topic_map(f.name)
+                assert 'welcome/index.adoc' in files
+                assert 'welcome/intro.adoc' in files
+                assert len(files) == 2
+            finally:
+                os.unlink(f.name)
+    
+    def test_extract_nested_topic_map(self):
+        """Test extracting files from a topic map with nested topics."""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.yml', delete=False) as f:
+            f.write("""---
+Name: Architecture
+Dir: architecture
+Topics:
+- Name: Overview
+  File: index
+- Name: Components
+  Dir: components
+  Topics:
+    - Name: API Server
+      File: api-server
+    - Name: Controller
+      File: controller
+""")
+            f.flush()
+            
+            try:
+                files = extract_files_from_topic_map(f.name)
+                assert 'architecture/index.adoc' in files
+                assert 'architecture/components/api-server.adoc' in files
+                assert 'architecture/components/controller.adoc' in files
+                assert len(files) == 3
+            finally:
+                os.unlink(f.name)
+    
+    def test_extract_multiple_documents(self):
+        """Test extracting files from a YAML file with multiple documents."""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.yml', delete=False) as f:
+            f.write("""---
+Name: Overview
+Dir: welcome
+Topics:
+- Name: Welcome
+  File: index
+---
+Name: Installation
+Dir: install
+Topics:
+- Name: Quick Start
+  File: quickstart
+""")
+            f.flush()
+            
+            try:
+                files = extract_files_from_topic_map(f.name)
+                assert 'welcome/index.adoc' in files
+                assert 'install/quickstart.adoc' in files
+                assert len(files) == 2
+            finally:
+                os.unlink(f.name)
+
+
+class TestProcessTopicGroup:
+    def test_process_simple_group(self):
+        """Test processing a simple topic group."""
+        group = {
+            'Name': 'Test Group',
+            'Dir': 'test',
+            'Topics': [
+                {'Name': 'Topic 1', 'File': 'topic1'},
+                {'Name': 'Topic 2', 'File': 'topic2'}
+            ]
+        }
+        
+        referenced_files = set()
+        process_topic_group(group, referenced_files)
+        
+        assert 'test/topic1.adoc' in referenced_files
+        assert 'test/topic2.adoc' in referenced_files
+    
+    def test_process_group_with_parent_dir(self):
+        """Test processing a topic group with a parent directory."""
+        group = {
+            'Name': 'Subgroup',
+            'Dir': 'sub',
+            'Topics': [
+                {'Name': 'Topic', 'File': 'topic'}
+            ]
+        }
+        
+        referenced_files = set()
+        process_topic_group(group, referenced_files, parent_dir='parent')
+        
+        assert 'parent/sub/topic.adoc' in referenced_files
+
+
+class TestGetAllTopicMapReferences:
+    def test_get_all_references(self):
+        """Test getting all references from all topic maps."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Create _topic_maps directory
+            topic_maps_dir = os.path.join(tmpdir, '_topic_maps')
+            os.makedirs(topic_maps_dir)
+            
+            # Create first topic map
+            topic_map1 = os.path.join(topic_maps_dir, 'map1.yml')
+            with open(topic_map1, 'w') as f:
+                f.write("""---
+Name: Group1
+Dir: group1
+Topics:
+- Name: Topic1
+  File: topic1
+""")
+            
+            # Create second topic map
+            topic_map2 = os.path.join(topic_maps_dir, 'map2.yml')
+            with open(topic_map2, 'w') as f:
+                f.write("""---
+Name: Group2
+Dir: group2
+Topics:
+- Name: Topic2
+  File: topic2
+""")
+            
+            references = get_all_topic_map_references(tmpdir)
+            assert 'group1/topic1.adoc' in references
+            assert 'group2/topic2.adoc' in references
+            assert len(references) == 2

rolfedh_doc_utils-0.1.2/doc_utils/unused_adoc.py

@@ -1,24 +0,0 @@
-# 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
-    )