diff --git a/documentation/architecture/filesystem.rst b/documentation/architecture/filesystem.rst index 8f31115..a78afe5 100644 --- a/documentation/architecture/filesystem.rst +++ b/documentation/architecture/filesystem.rst @@ -57,29 +57,160 @@ The main Python package follows the standard ``sources/`` directory pattern: .. code-block:: sources/ - ├── dynadoc/ # Main Python package - │ ├── __/ # Centralized import hub - │ │ ├── __init__.py # Re-exports core utilities - │ │ ├── imports.py # External library imports - │ │ └── nomina.py # python-dynadoc-specific naming constants - │ ├── __init__.py # Package entry point - │ ├── py.typed # Type checking marker - │ └── [modules].py # Feature-specific modules - + └── dynadoc/ # Main Python package + ├── __/ # Centralized import hub + │ ├── __init__.py # Re-exports core utilities + │ ├── doctab.py # Documentation fragment tables + │ ├── imports.py # External library imports + │ └── nomina.py # Project-specific naming constants + ├── renderers/ # Rendering subsystem + │ ├── __init__.py # Renderer exports + │ ├── __.py # Renderer-specific imports + │ └── sphinxad.py # Sphinx Autodoc reStructuredText renderer + ├── __init__.py # Package entry point + ├── assembly.py # Docstring assembly and decoration + ├── context.py # Context and control data structures + ├── factories.py # Factory functions for contexts + ├── interfaces.py # Protocols and data classes + ├── introspection.py # Object introspection and annotation processing + ├── nomina.py # Top-level type aliases and constants + ├── py.typed # Type checking marker + ├── userapi.py # Public API exports + └── xtnsapi.py # Extension API exports All package modules use the standard ``__`` import pattern as documented in the common architecture guide. +Module Responsibilities +------------------------------------------------------------------------------- + +**Core User Interface** + +* ``__init__.py``: Package entry point, self-documents via introspection +* ``userapi.py``: Exports user-facing API elements for import +* ``assembly.py``: Provides ``with_docstring`` decorator and + ``assign_module_docstring`` function + +**Processing Pipeline** + +* ``introspection.py``: Introspects objects, reduces annotations, extracts + documentation metadata +* ``assembly.py``: Orchestrates decoration, fragment collection, and recursive + processing +* ``renderers/sphinxad.py``: Renders information objects as reStructuredText + +**Configuration and Extension** + +* ``context.py``: Defines ``Context`` and ``IntrospectionControl`` data + structures with immutable configuration +* ``factories.py``: Provides ``produce_context`` factory with sensible defaults +* ``interfaces.py``: Defines protocols (``Notifier``, ``Renderer``, + ``VisibilityDecider``, ``FragmentRectifier``) and data classes + (``Doc``, ``Raises``, ``Default``, information classes) +* ``xtnsapi.py``: Re-exports extension API for custom renderers and + introspectors + +**Supporting Infrastructure** + +* ``nomina.py``: Type aliases and constants used throughout package +* ``__/imports.py``: Centralized external imports (dataclasses, enum, inspect, + re, types, typing, warnings, etc.) +* ``__/nomina.py``: Internal naming conventions and type definitions +* ``__/doctab.py``: Fragment table for package self-documentation + +Subpackage: Renderers +------------------------------------------------------------------------------- + +The ``renderers`` subpackage provides output format implementations: + +* ``sphinxad.py``: Default renderer producing Sphinx Autodoc-compatible + reStructuredText with field lists (``:argument:``, ``:type:``, ``:returns:``, + ``:rtype:``, ``:raises:``) +* Future renderers could support Markdown, NumPy/Google docstring styles, etc. + +Each renderer follows the ``Renderer`` protocol from ``interfaces.py``, +accepting a possessor object, information sequence, and context, returning a +formatted string. + Component Integration =============================================================================== +Module Dependencies +------------------------------------------------------------------------------- + +The package follows a layered dependency structure: + +* **Layer 0**: ``__/imports.py`` (external dependencies only) +* **Layer 1**: ``nomina.py``, ``__/nomina.py`` (type definitions) +* **Layer 2**: ``interfaces.py`` (protocols and data structures) +* **Layer 3**: ``context.py``, ``factories.py`` (configuration) +* **Layer 4**: ``introspection.py``, ``renderers/sphinxad.py`` (processing) +* **Layer 5**: ``assembly.py`` (orchestration) +* **Layer 6**: ``userapi.py``, ``xtnsapi.py``, ``__init__.py`` (public APIs) + +This layering ensures that configuration is independent of processing logic, +and protocols are defined before implementations. + +Public API Surface +------------------------------------------------------------------------------- + +**User API** (``dynadoc.*``): + +* Decorators: ``with_docstring``, ``exclude`` +* Functions: ``assign_module_docstring``, ``produce_context`` +* Annotation classes: ``Doc``, ``Fname``, ``Raises``, ``Default`` +* Enums: ``Visibilities``, ``ValuationModes``, ``NotificationLevels`` +* Protocols: ``Notifier``, ``Renderer``, ``VisibilityDecider``, + ``FragmentRectifier`` +* Configuration: ``Context``, ``IntrospectionControl``, + ``ClassIntrospectionControl``, ``ModuleIntrospectionControl`` + +**Extension API** (``dynadoc.xtnsapi.*``): + +Includes all user API plus internal utilities for renderer and introspector +implementations: + +* ``introspect``: Main introspection entry point +* ``reduce_annotation``: Annotation reduction with cache +* Information classes: ``ArgumentInformation``, ``AttributeInformation``, + ``ReturnInformation``, ``ExceptionInformation`` +* Additional support types: ``AnnotationsCache``, ``AdjunctsData`` + +Testing Organization +------------------------------------------------------------------------------- + +Tests mirror the source structure under ``tests/dynadoc/``: + +* Unit tests for each module (``test_introspection.py``, + ``test_assembly.py``, ``test_renderers_sphinxad.py``) +* Integration tests exercising full decoration pipeline +* Doctest examples in ``documentation/examples/`` + +Documentation Organization +------------------------------------------------------------------------------- + +Documentation follows standard structure: + +* ``documentation/examples/``: User-focused examples with executable doctests +* ``documentation/architecture/``: System design and architectural decisions +* Sphinx autodoc processes the package itself, dogfooding dynadoc's + capabilities + Architecture Evolution =============================================================================== -This filesystem organization provides a foundation that architect agents can -evolve as the project grows. For questions about organizational principles, -subpackage patterns, or testing strategies, refer to the comprehensive common -documentation: +This filesystem organization provides a foundation for future growth: + +**Potential Extensions** + +* Additional renderers in ``renderers/`` for other documentation formats +* Introspector registry in ``introspection.py`` for pluggable class handlers +* Type annotation filters in ``context.py`` for custom type transformations +* Resolver subsystem for handling forward references and stringified + annotations + +For questions about organizational principles, subpackage patterns, or testing +strategies, refer to the comprehensive common documentation: * `Architecture Patterns `_ * `Development Practices `_ diff --git a/documentation/architecture/summary.rst b/documentation/architecture/summary.rst index bab368a..3313d45 100644 --- a/documentation/architecture/summary.rst +++ b/documentation/architecture/summary.rst @@ -21,4 +21,231 @@ System Overview ******************************************************************************* -.. todo:: Describe the high-level system architecture, major components, and their relationships. \ No newline at end of file +Dynadoc is a Python library that bridges rich type annotations and automatic +documentation generation by extracting metadata from annotations and producing +formatted docstrings compatible with Sphinx Autodoc. + +Core Purpose +=============================================================================== + +Modern Python supports rich type annotations through ``Annotated`` types and +metadata objects like ``Doc`` from :pep:`727`. However, documentation tools +like Sphinx Autodoc cannot directly process this embedded metadata. Dynadoc +solves this problem by: + +* Introspecting annotated Python objects (modules, classes, functions) +* Extracting documentation from ``Doc`` objects, ``Raises`` specifications, + and other annotation metadata +* Generating comprehensive, formatted docstrings from this metadata +* Supporting customizable rendering for different documentation formats + +Major Components +=============================================================================== + +The system architecture follows a pipeline pattern with four primary layers: + +Introspection Layer +------------------------------------------------------------------------------- + +**Location**: ``sources/dynadoc/introspection.py`` + +Examines Python objects to extract documentable information: + +* **Annotation Access**: Retrieves annotations from modules, classes, and + functions using ``inspect.get_annotations`` +* **Annotation Reduction**: Processes complex generic types (``List[T]``, + ``Dict[K,V]``, ``Annotated[T, ...]``) to extract base types and metadata +* **Information Extraction**: Creates structured information objects + (``ArgumentInformation``, ``AttributeInformation``, ``ReturnInformation``, + ``ExceptionInformation``) from annotations +* **Cycle Detection**: Uses annotation cache to prevent infinite recursion + when processing self-referential types +* **Special Class Handling**: Supports custom introspectors for special types + (e.g., ``Enum`` members as class variables) + +The introspection system distinguishes between class attributes, instance +attributes, and module attributes based on annotation metadata (``ClassVar``) +and introspection control settings. + +Assembly Layer +------------------------------------------------------------------------------- + +**Location**: ``sources/dynadoc/assembly.py`` + +Orchestrates docstring generation and object decoration: + +* **Entry Points**: Provides ``with_docstring`` decorator for functions/classes + and ``assign_module_docstring`` for modules +* **Fragment Collection**: Gathers docstring fragments from multiple sources: + existing docstrings, explicit fragment arguments, fragment tables, and + introspection results +* **Recursive Decoration**: Processes module and class attributes based on + introspection targets (functions, classes, descriptors, nested modules) +* **Visit Tracking**: Uses weak references to prevent duplicate decoration of + the same object +* **Introspection Limiting**: Applies per-object limits through special + attributes (``_dynadoc_introspection_limit_``) + +The assembly layer coordinates between introspection and rendering, combining +all fragments into a final docstring. + +Rendering Layer +------------------------------------------------------------------------------- + +**Location**: ``sources/dynadoc/renderers/`` + +Converts structured information into formatted docstring text: + +* **Sphinx Autodoc Renderer** (``sphinxad.py``): Default renderer producing + reStructuredText compatible with Sphinx Autodoc +* **Annotation Formatting**: Converts type annotations to readable strings, + handling unions, generics, literals, and forward references +* **Style Options**: Supports "Legible" (extra spacing) and "Pep8" (compact) + formatting styles +* **Information Dispatch**: Routes different information types to specialized + formatters for arguments, attributes, returns, and exceptions +* **Module Attribute Handling**: Special formatting for TypeAlias and data + directives + +The rendering system is protocol-based, allowing custom renderers to be +plugged in for different output formats. + +Context and Configuration +------------------------------------------------------------------------------- + +**Location**: ``sources/dynadoc/context.py`` + +Provides configuration and customization through immutable context objects: + +* **Execution Context** (``Context``): Bundles customization points including + notifier, fragment rectifier, visibility decider, and name resolution + settings +* **Introspection Control** (``IntrospectionControl``): Configures introspection + behavior including targets (which object types to process), inheritance + handling, attribute scanning, and custom introspectors +* **Control Hierarchies**: Separate controls for class introspection + (``ClassIntrospectionControl``) and module introspection + (``ModuleIntrospectionControl``) +* **Limit Application**: Supports per-object introspection limits that + override global settings + +Context objects are immutable and frozen dataclasses, ensuring predictable +behavior throughout the processing pipeline. + +Data Flow +=============================================================================== + +Docstring generation follows this sequence: + +1. **Decoration Initiation**: User applies ``@with_docstring()`` decorator or + calls ``assign_module_docstring()`` + +2. **Fragment Collection**: Assembly layer gathers fragments from: + + * Existing docstring (if ``preserve=True``) + * Explicit fragments passed as arguments + * Fragment table lookups + * Object's ``_dynadoc_fragments_`` attribute + +3. **Introspection** (if enabled): + + * Access annotations from object + * Reduce complex annotations, extracting metadata + * Create information objects for arguments, attributes, returns, exceptions + * Apply visibility rules to filter attributes + +4. **Rendering**: Convert information objects to formatted text using + configured renderer + +5. **Assembly**: Combine all fragments (existing docstring, explicit fragments, + rendered introspection) with double newline separators + +6. **Assignment**: Set ``__doc__`` attribute on target object + +7. **Recursive Processing** (if targets configured): Repeat process for nested + classes, functions, and modules + +Design Patterns +=============================================================================== + +Protocol-Based Extensibility +------------------------------------------------------------------------------- + +Key extension points use protocols rather than inheritance: + +* ``Notifier``: Custom warning and error handling +* ``Renderer``: Alternative output formats beyond reStructuredText +* ``VisibilityDecider``: Custom rules for attribute visibility +* ``FragmentRectifier``: Custom fragment normalization +* ``ClassIntrospector``: Special handling for non-standard class structures + +This approach allows composition and runtime customization without subclassing. + +Annotation Reduction +------------------------------------------------------------------------------- + +Complex type annotations are "reduced" to simpler forms while extracting +metadata: + +* ``Annotated[str, Doc("name")]`` → base type ``str``, metadata ``Doc("name")`` +* ``List[Dict[str, int]]`` → recursively reduced with structure preserved +* Caching prevents redundant processing and detects reference cycles +* Forward references and string annotations handled gracefully + +Immutable Configuration +------------------------------------------------------------------------------- + +All configuration objects (``Context``, ``IntrospectionControl``, ``Default``) +are frozen dataclasses. Changes create new instances through methods like +``with_limit()`` and ``with_invoker_globals()``, ensuring thread-safety and +preventing accidental mutation. + +Fragment Composition +------------------------------------------------------------------------------- + +Docstrings are built from composable fragments rather than monolithic +generation. Fragments can come from: + +* Inline string literals +* ``Doc`` objects in annotations +* Named entries in fragment tables (reusable snippets) +* Existing docstrings on objects +* Rendered introspection results + +This enables incremental documentation and reuse of common text across a +project. + +Quality Attributes +=============================================================================== + +Extensibility +------------------------------------------------------------------------------- + +* Protocol-based customization points for rendering and visibility +* Pluggable introspectors for special class types +* Configurable fragment rectification and error notification +* Support for custom annotation metadata beyond ``Doc`` and ``Raises`` + +Correctness +------------------------------------------------------------------------------- + +* Cycle detection prevents infinite recursion in self-referential types +* Visit tracking prevents duplicate decoration +* Immutable configuration prevents state corruption +* Graceful handling of annotation access failures and malformed metadata + +Performance +------------------------------------------------------------------------------- + +* Annotation cache reduces redundant type processing +* Weak reference tracking has minimal memory overhead +* Single-pass introspection and rendering +* Introspection can be selectively disabled or limited per object + +Integration +------------------------------------------------------------------------------- + +* Sphinx-compatible output by default +* Works with standard Python ``inspect`` and ``typing`` modules +* Preserves existing docstrings and tooling workflows +* No modification of Python's annotation semantics \ No newline at end of file diff --git a/documentation/prd.rst b/documentation/prd.rst index 85bf640..6c31fc9 100644 --- a/documentation/prd.rst +++ b/documentation/prd.rst @@ -21,7 +21,410 @@ Product Requirements Document ******************************************************************************* -.. todo:: Define product requirements, user stories, and acceptance criteria. +Executive Summary +=============================================================================== -For PRD format and guidance, see the `requirements documentation guide -`_. \ No newline at end of file +Dynadoc is a Python library that bridges the gap between modern rich type +annotations (``Doc`` objects, ``Raises`` specifications, and other annotation +metadata) and automatic documentation generation tools like Sphinx Autodoc. By +introspecting annotated Python objects and extracting embedded documentation +metadata, Dynadoc generates comprehensive, formatted docstrings that integrate +seamlessly with existing documentation workflows. + +The library enables Python developers to write documentation once—as +annotation metadata—and automatically generate polished docstrings without +manual duplication or maintenance overhead. + +**Note on PEP 727**: While :pep:`727` (Documentation Metadata in Typing) has +been withdrawn, the ``Doc`` object it introduced remains available in +``typing_extensions`` and is maintained indefinitely by its maintainers. +Dynadoc provides its own fallback implementation should this support ever be +removed. + +Problem Statement +=============================================================================== + +Modern Python supports rich type annotations through ``Annotated`` types and +metadata objects like ``Doc`` (originally from the withdrawn :pep:`727`, now +maintained in ``typing_extensions``). However, documentation tools like Sphinx +Autodoc cannot directly process this embedded metadata, forcing developers to +choose between: + +1. **Manual duplication**: Writing the same information twice—once in + annotations and again in docstrings—leading to maintenance burden and + documentation drift +2. **Incomplete documentation**: Relying solely on type hints without + descriptive documentation, resulting in poor developer experience +3. **Custom tooling**: Building project-specific solutions that don't + generalize or integrate with standard documentation pipelines + +This problem affects Python library maintainers, API developers, and teams +adopting modern typing practices. The consequences include: + +* Increased maintenance cost from keeping annotations and docstrings + synchronized +* Documentation quality degradation as projects evolve +* Inconsistent documentation styles across codebases +* Reduced adoption of rich annotation metadata due to lack of tooling support + +Current workarounds involve writing custom Sphinx extensions or manually +copying annotation metadata into docstrings, neither of which provides a +reusable, standardized solution. + +Goals and Objectives +=============================================================================== + +Primary Objectives +------------------------------------------------------------------------------- + +* **REQ-GOAL-001** [Critical]: Extract documentation from PEP 727 ``Doc`` + objects and render as Sphinx-compatible docstrings + + *Success metric*: 100% of ``Doc`` annotations successfully extracted and + formatted + +* **REQ-GOAL-002** [Critical]: Support exception documentation via ``Raises`` + annotations in return types + + *Success metric*: All ``Raises`` specifications correctly rendered as + ``:raises:`` directives + +* **REQ-GOAL-003** [Critical]: Preserve existing docstring content while + augmenting with generated documentation + + *Success metric*: Original docstrings retained when ``preserve=True`` + +* **REQ-GOAL-004** [High]: Enable recursive documentation of modules, classes, + and functions + + *Success metric*: Configurable introspection targets process entire package + hierarchies + +Secondary Objectives +------------------------------------------------------------------------------- + +* **REQ-GOAL-005** [Medium]: Support custom renderers for alternative output + formats beyond Sphinx + + *Success metric*: Protocol-based extension points allow third-party renderers + +* **REQ-GOAL-006** [Medium]: Provide visibility controls for attribute + documentation + + *Success metric*: Custom visibility deciders filter attributes based on + project-specific rules + +* **REQ-GOAL-007** [Low]: Support fragment tables for reusable documentation + snippets + + *Success metric*: Named fragments referenced from multiple locations + +Functional Requirements +=============================================================================== + +Core Decoration +------------------------------------------------------------------------------- + +**REQ-FUNC-001** [Critical]: Function Decoration + + The ``@with_docstring()`` decorator generates parameter and return + documentation from function annotations. + + Acceptance Criteria: + + - Decorator accepts functions with annotated parameters + - ``Doc`` metadata extracted from ``Annotated`` types + - Generated docstring includes ``:argument:``, ``:type:``, ``:returns:``, and ``:rtype:`` fields + - Existing docstring content preserved when ``preserve=True`` + - Works with positional, keyword-only, and variadic parameters + +**REQ-FUNC-002** [Critical]: Class Decoration + + The ``@with_docstring()`` decorator documents class and instance attributes + from class annotations. + + Acceptance Criteria: + - Decorator processes class-level annotations + - Distinguishes between class variables (``ClassVar``) and instance variables + - Generated docstring includes ``:cvar:`` and ``:ivar:`` fields + - Supports inheritance of annotations when configured + - Handles properties and descriptors appropriately + +**REQ-FUNC-003** [Critical]: Module Documentation + + The ``assign_module_docstring()`` function documents module-level attributes + from module annotations. + + Acceptance Criteria: + - Accepts module object or string module name + - Processes module-level annotated variables + - Respects ``__all__`` for visibility when present + - Handles ``TypeAlias`` annotations specially + - Generates ``:py:data::`` and ``:py:type::`` directives + +Annotation Processing +------------------------------------------------------------------------------- + +**REQ-FUNC-004** [Critical]: Doc Extraction + + ``Doc`` objects in annotations are extracted and used as documentation text. + + Acceptance Criteria: + - ``Annotated[type, Doc("description")]`` extracts "description" + - Multiple ``Doc`` objects concatenated with proper spacing + - Multiline descriptions formatted correctly with indentation + - Works for parameters, returns, and attributes + +**REQ-FUNC-005** [Critical]: Raises Documentation + + ``Raises`` annotations in return types document exceptions that may be + raised. + + Acceptance Criteria: + - ``Raises(ExceptionClass, "description")`` generates ``:raises:`` field + - Supports single exception class or sequence of classes + - Multiple ``Raises`` annotations processed independently + - Description optional (produces field without description text) + +**REQ-FUNC-006** [High]: Complex Type Reduction + + Complex generic types are formatted readably in documentation. + + Acceptance Criteria: + - Union types rendered as ``type1 | type2`` + - Generic types rendered as ``Container[ElementType]`` + - Nested generics handled recursively + - Forward references and string annotations handled gracefully + - Cycle detection prevents infinite recursion + +Customization +------------------------------------------------------------------------------- + +**REQ-FUNC-007** [High]: Custom Renderers + + Custom renderers can generate documentation in formats other than Sphinx + reStructuredText. + + Acceptance Criteria: + - ``Renderer`` protocol defines extension interface + - Custom renderer receives possessor, informations, and context + - Renderer can access annotation details and descriptions + - Multiple output styles supported (e.g., Markdown, Google-style docstrings) + +**REQ-FUNC-008** [High]: Visibility Control + + Attribute visibility can be controlled to hide internal implementation + details. + + Acceptance Criteria: + - ``Visibilities.Conceal`` annotation forces attribute hiding + - ``Visibilities.Reveal`` annotation forces attribute documentation + - Custom ``VisibilityDecider`` callback for complex rules + - Default visibility based on naming conventions (``_private`` hidden) + - Respects ``__all__`` in modules + +**REQ-FUNC-009** [Medium]: Introspection Control + + Introspection configuration controls which object types are recursively + documented and documentation scope. + + Acceptance Criteria: + + - ``IntrospectionControl.targets`` specifies classes, functions, modules, and descriptors + - Per-object ``_dynadoc_introspection_limit_`` attribute overrides global settings + - Inheritance handling configurable per class + - Attribute scanning can be enabled or disabled + - Maximum recursion depth implicitly controlled by targets + +**REQ-FUNC-010** [Medium]: Fragment Tables + + Reusable documentation fragments can be defined and referenced from multiple + locations. + + Acceptance Criteria: + - Fragment table passed as ``table`` parameter + - ``Fname("fragment_name")`` annotation references table entries + - String fragments in decorator arguments look up table values + - Missing fragment names generate errors via notifier + - Fragments can come from module attributes (``_dynadoc_fragments_``) + +Configuration +------------------------------------------------------------------------------- + +**REQ-FUNC-011** [High]: Context Configuration + + ``Context`` objects configure and customize the documentation generation + process. + + Acceptance Criteria: + - ``produce_context()`` factory creates context with defaults + - Customizable notifier for warnings and errors + - Customizable fragment rectifier for text normalization + - Customizable visibility decider for attribute filtering + - Immutable context objects prevent accidental modification + +**REQ-FUNC-012** [Medium]: Default Value Handling + + Default value documentation can be controlled to suppress or replace values + as needed. + + Acceptance Criteria: + + - ``Default(mode=ValuationModes.Accept)`` uses actual default value + - ``Default(mode=ValuationModes.Suppress)`` omits default from documentation + - ``Default(mode=ValuationModes.Surrogate, surrogate="value")`` shows an alternative + - Applied via annotation metadata + - Works for function parameters and class/module attributes + +Non-Functional Requirements +=============================================================================== + +Performance +------------------------------------------------------------------------------- + +**REQ-PERF-001** [High]: Annotation caching prevents redundant type processing + + *Metric*: Each unique annotation processed at most once per decoration + +**REQ-PERF-002** [Medium]: Decoration overhead acceptable for import-time +execution + + *Metric*: Package with 100 decorated functions imports in under 1 second on + modern hardware + +Correctness +------------------------------------------------------------------------------- + +**REQ-CORR-001** [Critical]: Cycle detection prevents infinite recursion + + *Metric*: Self-referential types (e.g., ``Tree[Tree[T]]``) handled without + stack overflow + +**REQ-CORR-002** [Critical]: Multiple decoration of same object prevented + + *Metric*: Weak reference tracking ensures each object decorated exactly once + +**REQ-CORR-003** [High]: Malformed annotations handled gracefully + + *Metric*: Invalid annotation metadata generates warnings, not exceptions + +Compatibility +------------------------------------------------------------------------------- + +**REQ-COMPAT-001** [Critical]: Python 3.10+ support + + *Metric*: All features work on Python 3.10, 3.11, 3.12, 3.13+ + +**REQ-COMPAT-002** [Critical]: Sphinx Autodoc compatibility + + *Metric*: Generated docstrings parse correctly with sphinx.ext.autodoc + +**REQ-COMPAT-003** [High]: Type checker compatibility + + *Metric*: No false positives from mypy or pyright when using dynadoc + +Usability +------------------------------------------------------------------------------- + +**REQ-USE-001** [High]: Clear error messages for common mistakes + + *Metric*: Fragment not found, invalid annotation, and other errors provide + actionable guidance + +**REQ-USE-002** [Medium]: Sensible defaults require minimal configuration + + *Metric*: ``@with_docstring()`` works without parameters for typical use + cases + +**REQ-USE-003** [Medium]: API follows Python conventions + + *Metric*: Decorator and function names follow PEP 8, parameter names are + descriptive + +Extensibility +------------------------------------------------------------------------------- + +**REQ-EXT-001** [High]: Protocol-based extension points + + *Metric*: Custom renderers, notifiers, visibility deciders, fragment + rectifiers implementable without subclassing + +**REQ-EXT-002** [Medium]: Custom class introspectors + + *Metric*: Special class types (Enum, dataclass, etc.) can have specialized + introspection logic + +Constraints and Assumptions +=============================================================================== + +Technical Constraints +------------------------------------------------------------------------------- + +* Python 3.10+ required for modern ``typing`` features and ``inspect`` APIs +* Depends on Python stdlib modules: ``dataclasses``, ``enum``, ``inspect``, + ``re``, ``types``, ``typing``, ``warnings`` +* Depends on ``typing_extensions`` for ``Doc`` object support (provides + fallback if removed from ``typing_extensions``) +* Docstring generation happens at decoration time (import time or explicit + call), not lazily + +Design Assumptions +------------------------------------------------------------------------------- + +* Users follow ``Doc`` object conventions from withdrawn :pep:`727` as + implemented in ``typing_extensions`` +* Annotated types use ``Annotated[type, metadata]`` syntax from :pep:`593` +* Target documentation system supports Sphinx-style field lists (or custom + renderer provided) +* Module, class, and function docstrings are mutable (``__doc__`` writable) +* Weak references to decorated objects are viable for visit tracking + +Behavioral Assumptions +------------------------------------------------------------------------------- + +* Users want to preserve existing docstrings by default +* Public attributes (no leading underscore) should be documented by default +* Module ``__all__`` indicates exhaustive list of public API when present +* Introspection should be conservative by default (no recursive targets) + +Out of Scope +=============================================================================== + +The following features are explicitly excluded from the current product scope: + +**Alternative Documentation Standards** + +* Direct support for NumPy docstring format (can be added via custom renderer) +* Direct support for Google docstring format (can be added via custom renderer) +* Direct support for Markdown output (can be added via custom renderer) + +**Advanced Type Resolution** + +* Automatic resolution of all stringified annotations (forward references + handled on best-effort basis) +* Integration with type checkers for type inference +* Runtime type validation or checking + +**Documentation Generation** + +* Building Sphinx documentation (Dynadoc generates docstrings; Sphinx builds + docs) +* Generating standalone API documentation files +* Creating tutorials or user guides from code + +**IDE and Tooling Integration** + +* IDE plugins or language server extensions +* Direct integration with documentation hosting platforms +* Version control integration for tracking documentation changes + +**Behavioral Modifications** + +* Modifying Python's annotation semantics or evaluation +* Monkey-patching core typing or inspect modules +* Runtime performance optimization beyond caching + +**Project Management** + +* Sprint planning or development timelines are not included in this PRD +* Resource allocation and team assignments are determined separately \ No newline at end of file