Docstring Processing

@cache
def convert(docstring: str, docformat: str, source_file: Path | None) -> str:
    """
    Convert docstring from docformat to Markdown.
    
    Parameters:
    - docstring: str - Raw docstring content
    - docformat: str - Source format (google, numpy, restructuredtext, markdown)
    - source_file: Path | None - Source file path for relative references
    
    Returns:
    - str: Converted Markdown content
    
    Raises:
    - RuntimeError: If docstring processing fails
    """

def google(docstring: str) -> str:
    """
    Convert Google-style docstring sections into Markdown.
    
    Parameters:
    - docstring: str - Google-style docstring
    
    Returns:
    - str: Markdown-formatted docstring
    
    Supported sections:
    - Args/Arguments/Parameters
    - Returns/Return
    - Yields/Yield
    - Raises/Except/Exceptions
    - Note/Notes
    - Example/Examples
    - Attributes
    - References
    """

def embed_images(docstring: str, source_file: Path) -> str:
    """
    Embed local images referenced in docstrings as data URIs.
    
    Parameters:
    - docstring: str - Docstring text potentially containing image references
    - source_file: Path - Source file path for resolving relative image paths
    
    Returns:
    - str: Docstring with local images converted to data URIs
    
    Features:
    - Converts Markdown image syntax ![alt](path) to data URIs
    - Converts HTML img src attributes to data URIs
    - Automatic MIME type detection
    - Base64 encoding for binary image data
    """

def numpy(docstring: str) -> str:
    """
    Convert NumPy-style docstring sections into Markdown.
    
    Parameters:
    - docstring: str - NumPy-style docstring
    
    Returns:
    - str: Markdown-formatted docstring
    
    Supported sections:
    - Parameters
    - Returns
    - Yields
    - Raises
    - See Also
    - Notes
    - References
    - Examples
    """

def rst(contents: str, source_file: Path | None) -> str:
    """
    Convert reStructuredText syntax elements to Markdown.
    
    Parameters:
    - contents: str - reStructuredText content  
    - source_file: Path | None - Source file for resolving relative paths
    
    Returns:
    - str: Markdown-converted content
    
    Supported features:
    - Standard rST directives
    - Code blocks with syntax highlighting
    - Cross-references and hyperlinks
    - Include directives for external files
    """

def embed_images(html: str) -> str:
    """
    Embed image references as base64 data URIs.
    
    Parameters:
    - html: str - HTML content with image references
    
    Returns:
    - str: HTML with embedded image data
    
    Features:
    - Converts local image paths to base64 data URIs
    - Maintains image accessibility and alt text
    - Reduces external dependencies in generated docs
    """

from pdoc.docstrings import convert

# Convert different docstring formats
google_doc = '''
    Process data with advanced algorithms.
    
    Args:
        data (list): Input data to process
        method (str): Processing method ('fast' or 'accurate')
        
    Returns:
        dict: Processed results with metadata
        
    Raises:
        ValueError: If method is not recognized
'''

html_output = convert(google_doc, docformat="google")
print(html_output)  # HTML with structured sections

from pdoc.docstrings import google, numpy, rst

# Google-style docstring
google_text = '''
    Calculate statistics.
    
    Args:
        values: List of numeric values
        
    Returns:
        Statistical summary dictionary
'''
google_html = google(google_text)

# NumPy-style docstring  
numpy_text = '''
    Calculate statistics.
    
    Parameters
    ----------
    values : array_like
        List of numeric values
        
    Returns
    -------
    dict
        Statistical summary
'''
numpy_html = numpy(numpy_text)

# reStructuredText docstring
rst_text = '''
    Calculate statistics.
    
    :param values: List of numeric values
    :type values: list
    :returns: Statistical summary
    :rtype: dict
'''
rst_html = rst(rst_text)

from pdoc.docstrings import convert
from pdoc import render

# Configure docstring processing globally
render.configure(
    docformat="google",
    math=True,      # Enable LaTeX math
    mermaid=True    # Enable Mermaid diagrams
)

# Docstring with math and diagrams
advanced_docstring = '''
    Solve quadratic equation using the quadratic formula.
    
    The quadratic formula is: $x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}$
    
    Args:
        a (float): Coefficient of x²
        b (float): Coefficient of x  
        c (float): Constant term
        
    Returns:
        tuple: Two solutions (x1, x2)
        
    Example:
        ```mermaid
        graph TD
            A[Input: a,b,c] --> B[Calculate discriminant]
            B --> C{discriminant >= 0?}
            C -->|Yes| D[Two real solutions]
            C -->|No| E[Complex solutions]
        ```
'''

html_with_features = convert(advanced_docstring, "google")

from pdoc.docstrings import embed_images, convert

# Docstring with image references
doc_with_images = '''
    Process image data.
    
    ![Algorithm Diagram](./docs/algorithm.png)
    
    The algorithm works as shown in the diagram above.
'''

# Convert to HTML
html_content = convert(doc_with_images, "markdown")

# Embed images as base64
embedded_html = embed_images(html_content)
# Images are now embedded in the HTML as data URIs

from pdoc.docstrings import convert, embed_images
import re

def process_custom_docstring(docstring: str, docformat: str = "google") -> str:
    """Custom docstring processing with additional features"""
    
    # Pre-process: Handle custom tags
    docstring = re.sub(r'@deprecated', '**Deprecated:**', docstring)
    docstring = re.sub(r'@since (.+)', r'*Since version \1*', docstring)
    
    # Convert using pdoc
    html = convert(docstring, docformat)
    
    # Post-process: Embed images
    html = embed_images(html)
    
    # Add custom styling
    html = html.replace('<code>', '<code class="custom-code">')
    
    return html

# Usage
custom_doc = '''
    @deprecated
    This function is deprecated since version 2.0.
    
    @since 1.0
    
    Args:
        data: Input data
        
    Returns:
        Processed result
'''

processed_html = process_custom_docstring(custom_doc)

from pdoc import doc
from pdoc.docstrings import convert

# Process docstrings from actual Python objects
module_obj = doc.Module.from_name("my_package")

for name, member in module_obj.members.items():
    if hasattr(member.obj, '__doc__') and member.obj.__doc__:
        raw_docstring = member.obj.__doc__
        processed_html = convert(raw_docstring, "google")
        print(f"{name}: {processed_html[:100]}...")

GOOGLE_LIST_SECTIONS: list[str]
"""
List of recognized Google docstring section names:
['Args', 'Arguments', 'Parameters', 'Param', 'Params', 'Return', 'Returns', 
 'Yield', 'Yields', 'Raise', 'Raises', 'Except', 'Exceptions', 'Attributes', 
 'Example', 'Examples', 'Keyword Arguments', 'Keyword Args', 'Note', 'Notes', 
 'Other Parameters', 'References', 'See Also']
"""

GOOGLE_LIST_SECTION_ALIASES: dict[str, str]
"""
Mapping of section aliases to canonical names:
{'Param': 'Parameters', 'Params': 'Parameters', 'Return': 'Returns', 
 'Yield': 'Yields', 'Raise': 'Raises', 'Except': 'Exceptions', ...}
"""

AnyException: tuple[type[Exception], ...]
"""
Tuple of exception types for docstring processing error handling.
Includes various exception types that may be raised during parsing.
"""