yaml2rst.py: improve generators.

Author: ma10

tools/yaml2x/yaml2rst/generators/__init__.py

@@ -1,5 +1,14 @@
 """Package for RST file generation components."""
+from .base_generator import BaseGenerator, GeneratorError, ValidationError
 from .file_generator import FileGenerator, GeneratorConfig
-from .base_generator import BaseGenerator
+from .common_generators import ListBasedGenerator, SingleFileGenerator
 
-__all__ = ['FileGenerator', 'GeneratorConfig', 'BaseGenerator']
+__all__ = [
+    'BaseGenerator',
+    'GeneratorError',
+    'ValidationError',
+    'FileGenerator',
+    'GeneratorConfig',
+    'ListBasedGenerator',
+    'SingleFileGenerator',
+]

tools/yaml2x/yaml2rst/generators/base_generator.py

@@ -1,22 +1,54 @@
-"""Base generator class for generating RST content from data."""
+"""Base generator module for RST content generation."""
+from abc import ABC, abstractmethod
 from typing import Dict, Any, Iterator, Optional
+import logging
+from dataclasses import dataclass
+from pathlib import Path
 
-class BaseGenerator:
+class GeneratorError(Exception):
+    """Base exception for generator errors."""
+    pass
+
+class ValidationError(GeneratorError):
+    """Raised when data validation fails."""
+    pass
+
+@dataclass
+class GeneratorContext:
+    """Context information for generators."""
+    lang: str
+    base_dir: Path
+
+class BaseGenerator(ABC):
     """Base class for all content generators."""
 
-    def __init__(self, lang: str):
+    def __init__(self, lang: str, base_dir: Optional[Path] = None):
         """Initialize the generator.
         
         Args:
             lang: Language code for content generation
+            base_dir: Base directory for file operations (optional)
         """
-        self.lang = lang
+        self.context = GeneratorContext(
+            lang=lang,
+            base_dir=Path(base_dir) if base_dir else Path.cwd()
+        )
+        self.logger = logging.getLogger(self.__class__.__name__)
 
+    @property
+    def lang(self) -> str:
+        """Get language code for backward compatibility."""
+        return self.context.lang
+
+    @abstractmethod
     def generate(self) -> Iterator[Dict[str, Any]]:
         """Generate content data.
         
-        Returns:
-            Iterator yielding dictionaries containing template data
+        Yields:
+            Dictionary containing template data
+            
+        Raises:
+            GeneratorError: On generation failure
         """
         raise NotImplementedError("Subclasses must implement generate()")
 
@@ -27,3 +59,90 @@ def get_dependencies(self) -> list[str]:
             List of file paths that this generator depends on
         """
         return []
+
+    def validate_data(self, data: Dict[str, Any]) -> bool:
+        """Validate generated data.
+        
+        Args:
+            data: Data to validate
+            
+        Returns:
+            True if data is valid, False otherwise
+            
+        Raises:
+            ValidationError: If validation fails with specific reason
+        """
+        return True
+
+    def preprocess_data(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Preprocess data before template rendering.
+        
+        Args:
+            data: Data to preprocess
+            
+        Returns:
+            Preprocessed data
+        """
+        return data
+
+    def postprocess_data(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Postprocess data after template rendering.
+        
+        Args:
+            data: Data to postprocess
+            
+        Returns:
+            Postprocessed data
+        """
+        return data
+
+    def process_single_item(self, item: Any) -> Dict[str, Any]:
+        """Process a single item into template data.
+        
+        Args:
+            item: Item to process
+            
+        Returns:
+            Processed template data
+            
+        Raises:
+            GeneratorError: On processing failure
+        """
+        try:
+            data = self._process_item(item)
+            if not data:
+                self.logger.warning(f"No data generated for item: {item}")
+                return {}
+                
+            if not self.validate_data(data):
+                raise ValidationError(f"Data validation failed for item: {item}")
+                
+            processed_data = self.preprocess_data(data)
+            return self.postprocess_data(processed_data)
+            
+        except Exception as e:
+            self.logger.error(f"Error processing item {item}: {str(e)}")
+            raise GeneratorError(f"Failed to process item: {str(e)}") from e
+
+    def _process_item(self, item: Any) -> Dict[str, Any]:
+        """Internal method to process a single item.
+        
+        Args:
+            item: Item to process
+            
+        Returns:
+            Processed template data
+        """
+        raise NotImplementedError("Implement this method if using process_single_item")
+
+    def cleanup(self) -> None:
+        """Cleanup any resources after generation."""
+        pass
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.cleanup()

tools/yaml2x/yaml2rst/generators/common_generators.py

@@ -0,0 +1,53 @@
+"""Common base classes for specific types of generators."""
+from typing import Dict, Any, Iterator, TypeVar, Generic, List
+from abc import abstractmethod
+
+from a11y_guidelines import Faq, FaqTag, WcagSc, RelationshipManager
+from .base_generator import BaseGenerator
+
+T = TypeVar('T')
+
+class ListBasedGenerator(BaseGenerator, Generic[T]):
+    """Base class for generators that process lists of items."""
+
+    def generate(self) -> Iterator[Dict[str, Any]]:
+        """Generate content from a list of items."""
+        items = self.get_items()
+        self.logger.info(f"Processing {len(items)} items")
+        
+        for item in items:
+            try:
+                data = self.process_item(item)
+                if data and self.validate_data(data):
+                    yield self.postprocess_data(data)
+            except Exception as e:
+                self.logger.error(f"Error processing item {item}: {e}")
+                raise
+
+    @abstractmethod
+    def get_items(self) -> List[T]:
+        """Get list of items to process."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def process_item(self, item: T) -> Dict[str, Any]:
+        """Process a single item into template data."""
+        raise NotImplementedError
+
+class SingleFileGenerator(BaseGenerator):
+    """Base class for generators that produce a single file."""
+
+    @abstractmethod
+    def get_template_data(self) -> Dict[str, Any]:
+        """Get data for the template."""
+        raise NotImplementedError
+
+    def generate(self) -> Iterator[Dict[str, Any]]:
+        """Generate content for a single file."""
+        try:
+            data = self.get_template_data()
+            if data and self.validate_data(data):
+                yield self.postprocess_data(data)
+        except Exception as e:
+            self.logger.error(f"Error generating template data: {e}")
+            raise

tools/yaml2x/yaml2rst/generators/content_generators/__init__.py

@@ -8,30 +8,38 @@
     FaqTagIndexGenerator,
     FaqArticleIndexGenerator
 )
-from .reference_generator import (
+from .wcag_generator import (
     WcagMappingGenerator,
-    PriorityDiffGenerator,
+    PriorityDiffGenerator
+)
+from .reference_generator import (
     MiscDefinitionsGenerator,
     InfoToGuidelinesGenerator,
     InfoToFaqsGenerator,
     AxeRulesGenerator
 )
-from .makefile_generator import MakefileGenerator
+from .makefile_generator import (
+    MakefileGenerator,
+    MakefileConfig
+)
 
 __all__ = [
     'CategoryGenerator',
     'AllChecksGenerator',
     'CheckExampleGenerator',
+    'FaqGeneratorBase',
     'FaqArticleGenerator',
     'FaqTagPageGenerator',
     'FaqIndexGenerator',
     'FaqTagIndexGenerator',
     'FaqArticleIndexGenerator',
+    'WcagGeneratorBase',
     'WcagMappingGenerator',
     'PriorityDiffGenerator',
     'MiscDefinitionsGenerator',
     'InfoToGuidelinesGenerator',
     'InfoToFaqsGenerator',
     'AxeRulesGenerator',
-    'MakefileGenerator'
+    'MakefileGenerator',
+    'MakefileConfig'
 ]

tools/yaml2x/yaml2rst/generators/content_generators/category_generator.py

@@ -1,29 +1,36 @@
 """Generator for category pages."""
-from typing import Dict, Any, Iterator
+from typing import Dict, Any, Iterator, List
 
 from a11y_guidelines import RelationshipManager, Category
-from ..base_generator import BaseGenerator
+from ..common_generators import ListBasedGenerator
 
-class CategoryGenerator(BaseGenerator):
+class CategoryGenerator(ListBasedGenerator[str]):
     """Generates category pages with associated guidelines."""
 
-    def generate(self) -> Iterator[Dict[str, Any]]:
-        """Generate category page data.
-        
-        Yields:
-            Dictionary containing category and its guidelines data
-        """
-        rel = RelationshipManager()
-        for category, guidelines in rel.get_guidelines_to_category().items():
-            yield {
-                'filename': category,
-                'guidelines': [gl.template_data(self.lang) for gl in guidelines]
-            }
+    def __init__(self, lang: str):
+        super().__init__(lang)
+        self.relationship_manager = RelationshipManager()
+        self.categories_by_id = {cat.id: cat for cat in Category.list_all()}
+
+    def get_items(self) -> List[str]:
+        """Get all category IDs to process."""
+        return list(self.categories_by_id.keys())
+
+    def process_item(self, category_id: str) -> Dict[str, Any]:
+        """Process a single category."""
+        category_map = self.relationship_manager.get_guidelines_to_category()
+        category = self.categories_by_id[category_id]
+        guidelines = category_map[category_id]
+        return {
+            'filename': category_id,
+            'guidelines': [gl.template_data(self.lang) for gl in guidelines]
+        }
+
+    def validate_data(self, data: Dict[str, Any]) -> bool:
+        """Validate category page data."""
+        required_fields = ['filename', 'guidelines']
+        return all(field in data for field in required_fields)
 
     def get_dependencies(self) -> list[str]:
-        """Get category file dependencies.
-        
-        Returns:
-            List of category source file paths
-        """
+        """Get category file dependencies."""
         return [cat.get_dependency() for cat in Category.list_all()]