Nodes and Transforms

class bibliography(nodes.General, nodes.Element):
    """
    Node for representing a bibliography in the document tree.
    
    This node is created by BibliographyDirective and later replaced by
    a list of citations by BibliographyTransform during post-processing.
    
    Inherits from:
        nodes.General: General document element
        nodes.Element: Base element class
    """

class raw_latex(nodes.Special, nodes.Inline, nodes.PreBibliographic, nodes.FixedTextElement):
    """
    Node for representing raw LaTeX data in documents.
    
    Used for LaTeX-specific formatting that should be passed through
    directly to LaTeX output without processing.
    
    Inherits from:
        nodes.Special: Special formatting element
        nodes.Inline: Inline element
        nodes.PreBibliographic: Element that appears before bibliography
        nodes.FixedTextElement: Element with fixed text content
    """

def visit_raw_latex(self: LaTeXTranslator, node: raw_latex) -> None:
    """
    Called when entering a raw_latex node during LaTeX translation.
    
    Appends the node's raw source directly to the LaTeX body without
    any processing or escaping.
    
    Parameters:
        self: LaTeX translator instance
        node: The raw_latex node being processed
        
    Side Effects:
        Appends node.rawsource to self.body
    """

def depart_raw_latex(self: LaTeXTranslator, node: raw_latex) -> None:
    """
    Called when leaving a raw_latex node during LaTeX translation.
    
    This function performs no action as all processing is done
    in visit_raw_latex.
    
    Parameters:
        self: LaTeX translator instance  
        node: The raw_latex node being processed
    """

class BibliographyTransform(SphinxPostTransform):
    """
    Docutils transform to generate citation entries for bibliography nodes.
    
    This transform runs after all documents are parsed but before cross-references
    are resolved. It converts bibliography nodes into formatted citation lists
    based on the citations that were collected during parsing.
    
    Attributes:
        default_priority: int = 5  # Runs before ReferencesResolver (priority 10)
        backend: Backend instance for rendering formatted entries
    """
    
    def run(self, **kwargs) -> None:
        """
        Transform each bibliography node into a list of citations.
        
        For each bibliography node in the document:
        1. Retrieves the associated bibliography configuration
        2. Gets all citations that belong to this bibliography  
        3. Creates appropriate citation nodes (enumerated, bullet, or citation list)
        4. Formats each citation using pybtex backend
        5. Replaces the bibliography node with the formatted citation list
        
        Parameters:
            **kwargs: Additional keyword arguments (unused)
            
        Side Effects:
            - Modifies document tree by replacing bibliography nodes
            - Updates environment temp data for enumerated list counters
        """

def node_text_transform(node: docutils.nodes.Element) -> None:
    """
    Apply extra text transformations to a document node and its children.
    
    Currently handles:
    - Converting \\url patterns to proper reference nodes
    - Recursively processing all child elements
    
    This function processes special text patterns that need to be converted
    to proper docutils nodes for correct rendering in different output formats.
    
    Parameters:
        node: Document element to process
        
    Side Effects:
        - Modifies node tree by replacing text nodes with reference nodes
        - Recursively processes all child elements
    """

from sphinxcontrib.bibtex.nodes import bibliography, raw_latex

# Create a bibliography node (typically done by BibliographyDirective)
bib_node = bibliography("", docname="chapter1", ids=["bibliography-1"])

# Create a raw LaTeX node
latex_node = raw_latex("\\citep{smith2020}")
latex_node.rawsource = "\\citep{smith2020}"

# In sphinxcontrib.bibtex.__init__.setup()
app.add_post_transform(BibliographyTransform)

# In sphinxcontrib.bibtex.__init__.setup()
app.add_node(
    raw_latex, 
    latex=(visit_raw_latex, depart_raw_latex), 
    override=True
)

Document
├── pending_xref (from :cite: roles)
├── bibliography (from .. bibliography::)
│   └── [Replaced by citation list during transform]
└── Other content

Document  
├── pending_xref (resolved to formatted citations)
├── citation_list (bullet_list, enumerated_list, or citations)
│   ├── citation (with formatted entry and backrefs)
│   └── citation (...)
└── Other content