accelforge 0.0.1__py3-none-any.whl

docs/source/_ext/include_functions.py

@@ -0,0 +1,154 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+import importlib
+import inspect
+
+
+class IncludeFunctions(Directive):
+    required_arguments = 1  # fully-qualified name
+
+    def run(self):
+        fqname = self.arguments[0]
+        parts = fqname.split(".")
+
+        # --- progressively import the longest valid module ---
+        module = None
+        for i in range(len(parts), 0, -1):
+            try:
+                module = importlib.import_module(".".join(parts[:i]))
+                rest = parts[i:]
+                break
+            except ImportError:
+                continue
+
+        if module is None:
+            return []
+
+        obj = module
+        for part in rest:
+            if hasattr(obj, part):
+                obj = getattr(obj, part)
+            else:
+                return []
+
+        # --- Collect all functions ---
+        functions = {}  # {func_name: {'signature': ..., 'doc': ...}}
+
+        # Get all members
+        for name, member in inspect.getmembers(obj):
+            # Skip underscore-prefixed and special functions
+            if self._should_skip_function(name):
+                continue
+
+            # Check if it's a function or method
+            if inspect.isfunction(member) or inspect.ismethod(member):
+                doc = self._extract_summary_doc(member)
+                functions[name] = {
+                    'signature': self._get_signature(member),
+                    'doc': doc
+                }
+
+        # --- Build bullet list ---
+        if not functions:
+            return []
+
+        bullet_list = nodes.bullet_list()
+        for func_name in sorted(functions.keys()):
+            func_info = functions[func_name]
+            list_item = nodes.list_item()
+            para = nodes.paragraph()
+
+            # Function name as :py:func: role for clickable links
+            from sphinx.addnodes import pending_xref
+            refnode = pending_xref(
+                '',
+                refdomain='py',
+                reftype='func',
+                reftarget=fqname + '.' + func_name,
+                refwarn=True
+            )
+            # refnode += nodes.literal('', f"{func_name}{func_info['signature']}", classes=['xref', 'py', 'py-func'])
+            refnode += nodes.literal('', f"{func_name}()", classes=['xref', 'py', 'py-func'])
+            para += refnode
+
+            # Docstring
+            if func_info['doc']:
+                para += nodes.Text(f": {func_info['doc']}")
+
+            list_item += para
+            bullet_list += list_item
+
+        return [bullet_list]
+
+    def _should_skip_function(self, func_name):
+        """Check if a function should be skipped."""
+        return (
+            func_name.startswith('_') or
+            func_name.startswith('__')
+        )
+
+    def _get_signature(self, func):
+        """Get the function signature as a string."""
+        try:
+            sig = inspect.signature(func)
+            return str(sig)
+        except (ValueError, TypeError):
+            return "()"
+
+    def _extract_summary_doc(self, func):
+        """Extract the summary part of the docstring, stopping at section headers."""
+        # Get raw docstring
+        doc = getattr(func, "__doc__", None)
+        if not doc:
+            return None
+
+        # Clean and process the docstring
+        doc = inspect.cleandoc(doc)
+
+        section_headers = [
+            "Parameters", "Returns", "Postcondition", "Raises",
+            "Yields", "Examples", "Notes", "See Also", "Attributes",
+            "Methods", "References", "Warnings", "Args", "Return",
+            "Keyword Arguments", "Other Parameters"
+        ]
+
+        lines = doc.split('\n')
+        summary_lines = []
+
+        for line in lines:
+            stripped = line.strip()
+
+            # Stop at empty line followed by section header pattern
+            if not stripped:
+                # Check if we've already collected some content
+                if summary_lines:
+                    # Peek ahead to see if next non-empty line is a section
+                    continue
+
+            # Check if this line is a section header
+            if stripped in section_headers:
+                break
+
+            # Check if this line ends with a colon and might be a section header
+            if stripped.endswith(':'):
+                header_candidate = stripped[:-1].strip()
+                if header_candidate in section_headers:
+                    break
+
+            # Check for common docstring section patterns (underlined headers)
+            if stripped and all(c in '-=~' for c in stripped):
+                break
+
+            summary_lines.append(line)
+
+        # Join lines and clean up
+        summary = '\n'.join(summary_lines).strip()
+
+        # Replace multiple newlines/spaces with single space for better formatting
+        summary = ' '.join(summary.split())
+
+        return summary if summary else None
+
+
+def setup(app):
+    app.add_directive("include-functions", IncludeFunctions)

docs/source/_ext/include_notebook.py

@@ -0,0 +1,131 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import StringList
+import json
+import os
+import sys
+from paths import PROJECT_ROOT
+
+class IncludeNotebook(Directive):
+    """
+    Directive to include marked sections from Jupyter notebooks.
+
+    Usage:
+        .. include-notebook:: path/to/notebook.ipynb
+           :name: example_mac
+           :language: python
+    """
+
+    required_arguments = 1  # path to notebook
+    option_spec = {
+        "name": directives.unchanged_required,
+        "language": directives.unchanged,
+    }
+
+    def run(self):
+        env = self.state.document.settings.env
+        notebook_path = self.arguments[0]
+        marker_name = self.options.get("name")
+        language = self.options.get("language", "python")
+
+        notebook_path = os.path.normpath(
+            os.path.join(PROJECT_ROOT, notebook_path)
+        )
+
+        # Resolve relative paths
+        if not os.path.isabs(notebook_path):
+            source_dir = os.path.dirname(self.state.document.current_source)
+            notebook_path = os.path.normpath(os.path.join(source_dir, notebook_path))
+
+        if not os.path.exists(notebook_path):
+            error = self.state_machine.reporter.error(
+                f"Notebook file not found: {notebook_path}",
+                nodes.literal_block("", ""),
+                line=self.lineno,
+            )
+            return [error]
+
+        # Read and parse the notebook
+        try:
+            with open(notebook_path, "r", encoding="utf-8") as f:
+                notebook = json.load(f)
+        except Exception as e:
+            error = self.state_machine.reporter.error(
+                f"Error reading notebook: {e}",
+                nodes.literal_block("", ""),
+                line=self.lineno,
+            )
+            return [error]
+
+        # Extract all marked sections
+        content_sections = self._extract_marked_sections(notebook, marker_name)
+
+        if not content_sections:
+            warning = self.state_machine.reporter.warning(
+                f'Marker "# < DOC_INCLUDE_MARKER > {marker_name}" not found in {notebook_path}',
+                nodes.literal_block("", ""),
+                line=self.lineno,
+            )
+            return [warning]
+
+        # Concatenate all sections with double newline separator
+        content = "\n\n".join(content_sections)
+
+        # Remove newlines at the beginning and end
+        content = content.strip()
+
+        # Create a code block node
+        code_block = nodes.literal_block(content, content)
+        code_block["language"] = language
+        return [code_block]
+
+    def _extract_marked_sections(self, notebook, marker_name):
+        """
+        Extract content between DOC_INCLUDE_MARKER and DOC_INCLUDE_END (or end of cell).
+        Returns a list of all matching sections.
+        """
+        start_marker = f"# < DOC_INCLUDE_MARKER > {marker_name}"
+        end_marker = "# < DOC_INCLUDE_END >"
+        sections = []
+
+        for cell_idx, cell in enumerate(notebook.get("cells", [])):
+            if cell.get("cell_type") != "code":
+                continue
+
+            source = cell.get("source", [])
+
+            # Handle both string and list formats
+            if isinstance(source, str):
+                lines = source.split("\n")
+            else:
+                lines = source
+
+            # Look for all start markers in this cell
+            for i, line in enumerate(lines):
+                # Remove trailing newlines for comparison
+                line_stripped = line.rstrip("\n")
+
+                if start_marker in line_stripped:
+                    # Found the start marker, collect lines until end marker or end of cell
+                    content_lines = []
+                    for j in range(i + 1, len(lines)):
+                        if end_marker in lines[j]:
+                            break
+                        content_lines.append(lines[j].rstrip("\n"))
+
+                    # Join lines and strip trailing whitespace
+                    content = "\n".join(content_lines).strip()
+                    if content:  # Only add non-empty sections
+                        sections.append(content)
+
+        return sections
+
+
+def setup(app):
+    app.add_directive("include-notebook", IncludeNotebook)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/source/_ext/include_yaml.py

@@ -0,0 +1,119 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import StringList
+import re
+
+from paths import PROJECT_ROOT
+import os
+
+
+def grab_from_yaml_file(
+    yaml_file: str,
+    startfrom: str | None = None,
+    same_indent: bool = True,
+    include_lines_before: int = 0,
+) -> str:
+    """
+    Grab a section from a YAML file.
+
+    Args:
+        yaml_file:
+            The path to the YAML file.
+        startfrom:
+            The string to start from. If None, return the entire file.
+        same_indent:
+            Whether to include lines with the same indentation as the startfrom line, or
+            only lines with >= indentation.
+        include_lines_before:
+            The number of lines to include before the startfrom line.
+
+    Returns:
+        The section of the YAML file as a string.
+    """
+    with open(yaml_file, "r") as f:
+        contents = f.readlines()
+    start, end = 0, len(contents)
+    n_whitespace = 0
+
+    if startfrom is not None:
+        for i, line in enumerate(contents):
+            if re.findall(r"\b\s*" + startfrom + r"\b", line):
+                start = i
+                n_whitespace = len(re.findall(r"^\s*", line)[0])
+                break
+        else:
+            raise ValueError(f"{startfrom} not found in {yaml_file}")
+        for i, line in enumerate(contents[start + 1 :]):
+            if not line.strip():
+                continue
+            ws = len(re.findall(r"^\s*", line)[0])
+            if ws < n_whitespace or (not same_indent and ws == n_whitespace):
+                end = start + i + 1
+                break
+
+    contents = [c[n_whitespace:] for c in contents[start - include_lines_before : end]]
+    return "".join(contents)
+
+
+class IncludeYaml(Directive):
+    """
+    Directive to include content from a YAML file with optional filtering.
+
+    Usage:
+        .. include-yaml:: path/to/file.yaml
+           :startfrom: section_name
+           :same-indent:
+           :include-lines-before: 2
+    """
+
+    required_arguments = 1  # The YAML file path
+    optional_arguments = 0
+    option_spec = {
+        'startfrom': directives.unchanged,
+        'same-indent': directives.flag,
+        'include-lines-before': directives.nonnegative_int,
+    }
+    has_content = False
+
+    def run(self):
+        yaml_file = os.path.join(PROJECT_ROOT, self.arguments[0])
+        startfrom = self.options.get('startfrom', None)
+        same_indent = 'same-indent' in self.options
+        include_lines_before = self.options.get('include-lines-before', 0)
+
+        try:
+            content = grab_from_yaml_file(
+                yaml_file=yaml_file,
+                startfrom=startfrom,
+                same_indent=same_indent,
+                include_lines_before=include_lines_before,
+            )
+        except Exception as e:
+            error = self.state_machine.reporter.error(
+                f'Error reading YAML file "{yaml_file}": {str(e)}',
+                nodes.literal_block('', ''),
+                line=self.lineno
+            )
+            return [error]
+
+        # Create a literal block with YAML syntax highlighting
+        literal = nodes.literal_block(content, content)
+        literal['language'] = 'yaml'
+
+        return [literal]
+
+
+def setup(app):
+    """
+    Setup function for the Sphinx extension.
+
+    Add this to your conf.py:
+        extensions = ['path.to.this.module']
+    """
+    app.add_directive('include-yaml', IncludeYaml)
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/source/_ext/inherited_attributes.py

@@ -0,0 +1,222 @@
+from sphinx.ext.autodoc import ClassDocumenter, INSTANCEATTR, ObjectMember
+from sphinx.util.inspect import safe_getattr
+import inspect
+from pydantic import BaseModel
+
+
+# Default ignore lists
+DEFAULT_IGNORE = [
+    'object',
+    'ABC',
+    'BaseModel',
+    'Enum',
+    'Flag',
+    'IntEnum',
+    'IntFlag',
+    'Generic',
+    'object',
+    'ABC',
+    'BaseModel',
+    'ParsableModel',
+    'ParsableList',
+    'ParsableDict',
+    'ParseExtras',
+    'NonParsableModel',
+    '_FromYAMLAble',
+    'ParsesTo',
+    'Enum',
+    'Flag',
+    'IntEnum',
+    'IntFlag',
+    'Generic',
+    'model_validate',
+    'model_validate_json',
+    'model_validate_strings',
+    'parse_file',
+    'parse_obj',
+    'parse_raw',
+    'schema',
+    'schema_json',
+    'model_dump',
+    'model_dump_json',
+    'model_copy',
+    'construct',
+    'copy',
+    'dict',
+    'json',
+    'update_forward_refs',
+    'model_post_init',
+    'model_config',
+    'model_fields',
+    'model_fields_set',
+    'model_extra',
+    'model_private',
+    'model_rebuild',
+    'get_fields',
+    'get_validator',
+    'all_fields_default',
+    'model_dump_non_none',
+] + list(BaseModel.__dict__.keys())
+
+class InheritedAttributesClassDocumenter(ClassDocumenter):
+    """Enhanced ClassDocumenter that includes inherited attributes."""
+
+    priority = ClassDocumenter.priority + 1
+
+    def get_object_members(self, want_all):
+        """Override to include inherited members."""
+        # Get the normal members first
+        members_check_module, members = super().get_object_members(want_all)
+
+        # Get configuration
+        config = self.env.config
+        ignore = getattr(config, 'inherited_attributes_ignore', []) + DEFAULT_IGNORE
+
+        # Collect ALL attributes defined directly on this class (not inherited)
+        own_members = set()
+        if hasattr(self.object, '__dict__'):
+            own_members.update(self.object.__dict__.keys())
+        if hasattr(self.object, 'model_fields'):
+            own_members.update(self.object.model_fields.keys())
+        if hasattr(self.object, '__fields__'):
+            own_members.update(self.object.__fields__.keys())
+
+        # Filter out members from ignored classes that were already included
+        # BUT keep them if they're overridden in the current class
+        filtered_members = []
+        for member in members:
+            if hasattr(member, '__getitem__') and len(member) >= 4:
+                name = member[0]
+                member_class = member[3] if len(member) > 3 else None
+
+                # Keep if it's defined directly on this class
+                if name in own_members:
+                    filtered_members.append(member)
+                    continue
+
+                # Skip if from an ignored class (and not overridden)
+                if member_class and self._should_ignore_class(member_class, ignore):
+                    continue
+
+                # Skip ignored functions/attributes (only if not overridden)
+                if name in ignore:
+                    continue
+
+                filtered_members.append(member)
+            else:
+                filtered_members.append(member)
+
+        members = filtered_members
+
+        # Get MRO
+        try:
+            mro = inspect.getmro(self.object)
+        except (AttributeError, TypeError):
+            return members_check_module, members
+
+        # Track seen names - includes both members from super() and own_members
+        # ObjectMember is a namedtuple, access by index
+        seen_names = set()
+        for member in members:
+            if hasattr(member, '__getitem__'):
+                seen_names.add(member[0])
+        # Add all own members to seen_names to prevent inheritance
+        seen_names.update(own_members)
+
+        # Collect inherited members
+        inherited = []
+
+        for parent_class in mro[1:]:  # Skip self
+            # Check if we should stop FIRST, before processing any members
+            if self._should_ignore_class(parent_class, ignore):
+                break
+
+            # Get members from parent
+            for name in dir(parent_class):
+                # Skip underscore-prefixed
+                if name.startswith('_'):
+                    continue
+
+                # Skip if already seen (including own_members)
+                if name in seen_names:
+                    continue
+
+                # Skip ignored
+                if name in ignore:
+                    continue
+
+                try:
+                    obj = safe_getattr(parent_class, name)
+
+                    # Skip callables in ignore list
+                    if callable(obj) and name in ignore:
+                        continue
+
+                    # Create ObjectMember
+                    inherited.append(ObjectMember(name, obj))
+                    seen_names.add(name)
+
+                except (AttributeError, TypeError):
+                    continue
+
+            # Check Pydantic fields
+            if hasattr(parent_class, 'model_fields'):
+                for field_name in parent_class.model_fields:
+                    if field_name.startswith('_'):
+                        continue
+                    # Skip if already seen (including own_members)
+                    if field_name in seen_names:
+                        continue
+                    if field_name in ignore:
+                        continue
+
+                    inherited.append(ObjectMember(field_name, INSTANCEATTR))
+                    seen_names.add(field_name)
+
+            elif hasattr(parent_class, '__fields__'):
+                for field_name in parent_class.__fields__:
+                    if field_name.startswith('_'):
+                        continue
+                    # Skip if already seen (including own_members)
+                    if field_name in seen_names:
+                        continue
+                    if field_name in ignore:
+                        continue
+
+                    inherited.append(ObjectMember(field_name, INSTANCEATTR))
+                    seen_names.add(field_name)
+
+        # Combine
+        all_members = list(members) + inherited
+
+        return members_check_module, all_members
+
+    def _should_ignore_class(self, cls, ignore_classes):
+        """Check if a class should be ignored."""
+        name = getattr(cls, '__name__', '')
+        module = getattr(cls, '__module__', '')
+
+        # Ignore if not part of accelforge package
+        if module and not module.startswith('accelforge'):
+            return True
+
+        # Check against ignore list using just the class name
+        for ignore_pattern in ignore_classes:
+            if name == ignore_pattern:
+                return True
+
+        return False
+
+def setup(app):
+    """Setup the extension."""
+    # Only add config value if it doesn't exist
+    if not hasattr(app.config, 'inherited_attributes_ignore'):
+        app.add_config_value('inherited_attributes_ignore', [], 'env')
+
+    app.add_autodocumenter(InheritedAttributesClassDocumenter, override=True)
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/source/_ext/paths.py

@@ -0,0 +1,4 @@
+import os
+from pathlib import Path
+
+PROJECT_ROOT = os.path.abspath(Path(__file__).parent.parent.parent.parent)