.readthedocs.yaml

# .readthedocs.yaml
# Read the Docs configuration file for memories-dev

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"
  jobs:
    pre_build:
      # Install core dependencies
      - python -m pip install --upgrade pip setuptools wheel
      - pip install docutils==0.18.1
      - pip install sphinx==7.1.2 sphinx-rtd-theme==1.3.0 sphinxcontrib-jquery>=4.1
      - pip install -r docs/requirements.txt
      
      # Create mock directories
      - mkdir -p data/models data/cache config docs/source/api_reference
      
      # Create our mock_diffusers.py file
      - |
        cat > mock_diffusers.py << 'EOL'
        """
        Mock diffusers module for documentation builds.
        
        This module creates a mock structure that mimics the diffusers package
        but raises ImportError when any actual functionality is imported.
        This prevents documentation builds from failing due to missing dependencies.
        """
        
        import os
        import sys
        import types
        
        class MockDiffusers:
            """Mock class for diffusers package."""
            
            def __init__(self):
                self.__all__ = []
                self.__path__ = []
                self.__file__ = __file__
                self.__name__ = "diffusers"
                
            def __getattr__(self, name):
                """Raise ImportError for any attribute access."""
                raise ImportError(
                    f"The diffusers.{name} module is not available. "
                    "This is a mock module created for documentation builds."
                )
        
        def setup_mock_diffusers():
            """Set up mock diffusers module in sys.modules."""
            # Create the mock module
            mock_diffusers = MockDiffusers()
            
            # Add it to sys.modules
            sys.modules['diffusers'] = mock_diffusers
            
            # Create common submodules
            for submodule in [
                'diffusers.loaders',
                'diffusers.models',
                'diffusers.pipelines',
                'diffusers.schedulers',
                'diffusers.utils',
            ]:
                sys.modules[submodule] = types.ModuleType(submodule)
                setattr(sys.modules[submodule], '__file__', __file__)
                setattr(sys.modules[submodule], '__path__', [])
                setattr(sys.modules[submodule], '__package__', submodule)
                
                # Make any attribute access raise ImportError
                def get_attr_raiser(submodule_name):
                    def __getattr__(name):
                        raise ImportError(
                            f"The {submodule_name}.{name} module is not available. "
                            "This is a mock module created for documentation builds."
                        )
                    return __getattr__
                    
                setattr(sys.modules[submodule], '__getattr__', get_attr_raiser(submodule))
            
            print("Mock diffusers module has been set up successfully.")
            return mock_diffusers
        
        if __name__ == "__main__":
            # If run directly, set up the mock module
            setup_mock_diffusers()
        EOL
      
      # Create a script to check if diffusers is properly mocked
      - |
        cat > check_mocks.py << 'EOL'
        #!/usr/bin/env python
        """
        Check if the diffusers module is properly mocked.
        
        This script attempts to import diffusers and its submodules to verify
        that they are properly mocked and will raise appropriate ImportError
        exceptions when accessed.
        """
        
        import os
        import sys
        import importlib
        import traceback
        
        def test_import(module_name):
            """Test importing a module and report the result."""
            print(f"Testing import of {module_name}...")
            try:
                module = importlib.import_module(module_name)
                print(f"  ✓ Successfully imported {module_name}")
                print(f"  Module type: {type(module)}")
                print(f"  Module path: {getattr(module, '__file__', 'No __file__ attribute')}")
                print(f"  Module attributes: {dir(module)[:5]}...")
                
                # Try accessing an attribute to see if it raises ImportError
                try:
                    getattr(module, 'nonexistent_attribute')
                    print(f"  ✗ ERROR: Accessing nonexistent attribute did not raise ImportError")
                except ImportError:
                    print(f"  ✓ Accessing nonexistent attribute correctly raised ImportError")
                except Exception as e:
                    print(f"  ✗ ERROR: Accessing nonexistent attribute raised {type(e).__name__} instead of ImportError")
                    
                return True
            except ImportError as e:
                print(f"  ✓ ImportError raised as expected: {e}")
                return False
            except Exception as e:
                print(f"  ✗ ERROR: Unexpected exception: {type(e).__name__}: {e}")
                traceback.print_exc()
                return False
        
        def main():
            """Main function to test diffusers mocking."""
            print("=" * 80)
            print("CHECKING DIFFUSERS MOCKING")
            print("=" * 80)
            
            # Check environment
            print("\nEnvironment:")
            print(f"Python version: {sys.version}")
            print(f"DISABLE_DIFFUSERS env var: {os.environ.get('DISABLE_DIFFUSERS', 'Not set')}")
            print(f"sys.path: {sys.path[:3]}...")
            
            # Test importing diffusers
            print("\nTesting diffusers imports:")
            modules_to_test = [
                'diffusers',
                'diffusers.loaders',
                'diffusers.loaders.single_file',
                'diffusers.pipelines',
                'diffusers.models',
            ]
            
            for module_name in modules_to_test:
                test_import(module_name)
                print()
            
            # Check if diffusers is in sys.modules
            print("\nChecking sys.modules:")
            for module_name in modules_to_test:
                if module_name in sys.modules:
                    module = sys.modules[module_name]
                    print(f"{module_name} is in sys.modules")
                    print(f"  Type: {type(module)}")
                    print(f"  File: {getattr(module, '__file__', 'No __file__ attribute')}")
                else:
                    print(f"{module_name} is NOT in sys.modules")
            
            print("\nMock testing complete!")
        
        if __name__ == "__main__":
            main()
        EOL
      
      # Create a separate setup function file
      - |
        cat > docs/source/sphinx_setup.py << 'EOL'
        """
        Setup function for Sphinx documentation.
        
        This module provides the setup function for Sphinx to block diffusers modules.
        """
        
        def setup(app):
            """
            Setup function for Sphinx.
            
            This function is called by Sphinx during initialization.
            It blocks diffusers modules from being documented.
            """
            # Store a flag on the app object
            app._mock_diffusers_enabled = True
            
            # Return empty dict to indicate success
            return {}
        EOL
      
      # Create a simplified patch script without any variable assignments
      - |
        cat > docs/source/conf_patch.py << 'EOL'
        #!/usr/bin/env python
        """Patch for conf.py to exclude problematic modules."""
        import os
        import sys
        import re

        try:
            # Create directories
            os.makedirs('data/models', exist_ok=True)
            os.makedirs('data/cache', exist_ok=True)
            os.makedirs('config', exist_ok=True)
            
            # Create mock config
            if not os.path.exists('config/db_config.yml'):
                with open('config/db_config.yml', 'w') as f:
                    f.write('# Mock config\ndatabases:\n  memory_store:\n    host: localhost\n')
            
            # Update conf.py to exclude problematic modules
            conf_path = 'docs/source/conf.py'
            if not os.path.exists(conf_path):
                print(f"Warning: {conf_path} does not exist. Creating a minimal version.")
                with open(conf_path, 'w') as f:
                    f.write('# Auto-generated minimal conf.py\nautodoc_mock_imports = []\n')
            
            with open(conf_path, 'r') as f:
                content = f.read()
            
            # Add diffusers to autodoc_mock_imports
            if 'autodoc_mock_imports = [' in content:
                # Check if diffusers is already in the list
                if not re.search(r'autodoc_mock_imports\s*=\s*\[[^\]]*"diffusers"', content):
                    content = content.replace(
                        'autodoc_mock_imports = [',
                        'autodoc_mock_imports = [\n    "diffusers.loaders.single_file",\n    "diffusers",\n    "diffusers.pipelines",\n    "diffusers.loaders",\n'
                    )
            else:
                print("Warning: autodoc_mock_imports not found in conf.py. Adding it.")
                content += '\n\n# Added by conf_patch.py\nautodoc_mock_imports = [\n    "diffusers.loaders.single_file",\n    "diffusers",\n    "diffusers.pipelines",\n    "diffusers.loaders",\n]\n'
            
            # Add code to import our mock_diffusers at the top of conf.py
            if not "import mock_diffusers" in content:
                import_section = "# -- Path setup --------------------------------------------------------------"
                if import_section in content:
                    # Add after the import section
                    content = content.replace(
                        import_section,
                        import_section + "\n\n# Import mock diffusers\ntry:\n    import sys\n    sys.path.insert(0, os.path.abspath('../..'))\n    import mock_diffusers\n    mock_diffusers.setup_mock_diffusers()\n    print('Successfully loaded mock diffusers')\nexcept Exception as e:\n    print(f'Error loading mock diffusers: {e}')\n"
                    )
                else:
                    # Add at the beginning
                    content = "# Import mock diffusers\ntry:\n    import sys\n    sys.path.insert(0, os.path.abspath('../..'))\n    import mock_diffusers\n    mock_diffusers.setup_mock_diffusers()\n    print('Successfully loaded mock diffusers')\nexcept Exception as e:\n    print(f'Error loading mock diffusers: {e}')\n\n" + content
            
            # Import the setup function from sphinx_setup.py
            if not "from sphinx_setup import setup" in content:
                if "def setup(app):" in content:
                    # Replace the existing setup function with an import
                    setup_pattern = r"def setup\(app\):.*?(?=\n\w|\Z)"
                    setup_replacement = "# Import setup function from sphinx_setup.py\nfrom sphinx_setup import setup"
                    content = re.sub(setup_pattern, setup_replacement, content, flags=re.DOTALL)
                else:
                    # Add the import at the end
                    content += "\n\n# Import setup function from sphinx_setup.py\nfrom sphinx_setup import setup\n"
            
            # Write updated conf.py
            with open(conf_path, 'w') as f:
                f.write(content)
            
            print("Updated conf.py to exclude problematic modules")
        except Exception as e:
            print(f"Error in conf_patch.py: {e}")
            # Continue with the build even if patching fails
            sys.exit(0)
        EOL
      
      # Create our pre-import script
      - |
        cat > docs/source/conf_pre_import.py << 'EOL'
        """
        Pre-import configuration for Sphinx documentation.
        
        This script is imported at the very beginning of conf.py before any other imports.
        It sets up mocks and environment variables to ensure the documentation build succeeds.
        """
        
        import os
        import sys
        import types
        
        # Set environment variables
        os.environ['DISABLE_DIFFUSERS'] = '1'
        
        # Add parent directory to path so we can import our mock_diffusers
        sys.path.insert(0, os.path.abspath('../..'))
        
        # Create a simple mock for diffusers in case mock_diffusers.py fails
        class MockModule:
            """Simple mock module that raises ImportError for any attribute access."""
            
            def __init__(self, name):
                self.__name__ = name
                self.__all__ = []
                self.__path__ = []
                self.__file__ = __file__
                
            def __getattr__(self, name):
                """Raise ImportError for any attribute access."""
                raise ImportError(
                    f"The {self.__name__}.{name} module is not available. "
                    "This is a mock module created for documentation builds."
                )
        
        # Create mock diffusers module
        sys.modules['diffusers'] = MockModule('diffusers')
        
        # Create common submodules
        for submodule in [
            'diffusers.loaders',
            'diffusers.models',
            'diffusers.pipelines',
            'diffusers.schedulers',
            'diffusers.utils',
        ]:
            sys.modules[submodule] = MockModule(submodule)
        
        # Try to import the more sophisticated mock_diffusers
        try:
            import mock_diffusers
            mock_diffusers.setup_mock_diffusers()
            print('Successfully loaded mock_diffusers module')
        except Exception as e:
            print(f'Error loading mock_diffusers module: {e}')
            print('Using simple mock module instead')
        
        # Add diffusers to autodoc_mock_imports
        autodoc_mock_imports = [
            "diffusers",
            "diffusers.loaders",
            "diffusers.loaders.single_file",
            "diffusers.pipelines",
            "diffusers.models",
            "diffusers.schedulers",
            "diffusers.utils",
        ]
        
        # Print confirmation
        print("Pre-import configuration completed successfully")
        EOL
      
      # Run the patch script
      - python docs/source/conf_patch.py || echo "Error running conf_patch.py, continuing anyway"
      
      # Run our mock diffusers setup
      - python mock_diffusers.py || echo "Error running mock_diffusers.py, continuing anyway"
      
      # Test our mocking
      - DISABLE_DIFFUSERS=1 python check_mocks.py || echo "Error running check_mocks.py, continuing anyway"
      
      # Install the package in development mode with a special flag to disable diffusers
      - DISABLE_DIFFUSERS=1 pip install -e .
      
      # Generate API documentation with exclude pattern
      - sphinx-apidoc -o docs/source/api_reference memories/ --exclude="*diffusers*" --force || echo "API doc generation failed"

# Sphinx configuration
sphinx:
  builder: html
  configuration: docs/source/conf.py
  fail_on_warning: false

# Python requirements
python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs
    
# Build documentation in additional formats
formats:
  - htmlzip
  - pdf

# Don't use submodules for documentation
submodules:
  include: []
  recursive: false

# Configure search
search:
  ranking:
    api_reference/*: -1
    changelog.html: 3
    index.html: 5
    getting_started/*: 4