Citation System

class BibtexDomain(Domain):
    """
    Sphinx domain for the bibtex extension.
    
    Attributes:
        name: str = "cite"
        label: str = "BibTeX Citations"
        data_version: int = 4
    """
    
    @property
    def bibdata(self) -> BibData:
        """Information about the bibliography files."""
    
    @property
    def bibliographies(self) -> Dict[BibliographyKey, BibliographyValue]:
        """Map storing information about each bibliography directive."""
    
    @property 
    def citations(self) -> List[Citation]:
        """Citation data."""
        
    @property
    def citation_refs(self) -> List[CitationRef]:
        """Citation reference data."""
    
    def clear_doc(self, docname: str) -> None:
        """Clear document-specific data when document is rebuilt."""
        
    def merge_domaindata(self, docnames: AbstractSet[str], otherdata: Dict) -> None:
        """Merge domain data from parallel builds."""
        
    def env_updated(self) -> Iterable[str]:
        """Process citations after all doctrees are parsed."""
        
    def resolve_xref(
        self,
        env: BuildEnvironment,
        fromdocname: str,
        builder: Builder,
        typ: str,
        target: str,
        node: pending_xref,
        contnode: docutils.nodes.Element,
    ) -> docutils.nodes.Element:
        """Replace citation reference node with formatted citation."""
        
    def get_all_cited_keys(self, docnames: List[str]) -> Iterable[str]:
        """Yield all citation keys for given documents in citation order."""
        
    def get_entries(self, bibfiles: List[Path]) -> Iterable[Entry]:
        """Return all bibliography entries from bib files."""
        
    def get_filtered_entries(
        self, bibliography_key: BibliographyKey
    ) -> Iterable[Tuple[str, Entry]]:
        """Return bibliography entries filtered by filter expression."""
        
    def get_formatted_entries(
        self,
        bibliography_key: BibliographyKey,
        docnames: List[str],
        tooltips: bool,
        tooltips_style: str,
    ) -> Iterable[Tuple[Entry, FormattedEntry, Optional[FormattedEntry]]]:
        """Get formatted entries with pybtex labels and optional tooltips."""

class BibliographyDirective(Directive):
    """
    Class for processing the bibliography directive.
    
    Options:
        cited: Include only cited entries
        notcited: Include only non-cited entries  
        all: Include all entries
        filter: Custom filter expression
        style: Bibliography style (overrides default)
        list: List type ('citation', 'bullet', 'enumerated')
        enumtype: Enumeration type for enumerated lists
        start: Start number or 'continue'
        labelprefix: Prefix for bibliography labels
        keyprefix: Prefix for citation keys
    """
    
    required_arguments: int = 0
    optional_arguments: int = 1
    has_content: bool = True
    
    def run(self) -> Sequence[docutils.nodes.Node]:
        """
        Process .bib files, set file dependencies, and create bibliography node.
        
        Returns:
            List containing bibliography node to be transformed later
        """

class CiteRole(XRefRole):
    """
    Class for processing the cite role.
    
    Supports role variants:
        :cite:p: - Parenthetical citations: (Author, 2020)
        :cite:t: - Textual citations: Author (2020)
    """
    
    def result_nodes(self, document, env, node, is_ref) -> Tuple[List[docutils.nodes.Node], List]:
        """
        Associate the pending_xref with the cite domain and note citation keys.
        
        Parameters:
            document: Document containing the citation
            env: Sphinx build environment
            node: Citation reference node
            is_ref: Whether this is a reference
            
        Returns:
            Tuple of (nodes, messages)
        """

class CitationRef(NamedTuple):
    """Information about a citation reference."""
    citation_ref_id: str  # Unique ID of citation reference
    docname: str  # Document name where citation appears
    line: int  # Line number in document
    targets: List[CitationTarget]  # Citation targets (key, pre, post)

class BibliographyKey(NamedTuple):
    """Unique key for each bibliography directive."""
    docname: str  # Name of document containing bibliography
    id_: str  # ID of bibliography node in document

class BibliographyValue(NamedTuple):
    """Information about a bibliography directive."""
    line: int  # Line number of directive
    bibfiles: List[Path]  # List of bib files
    style: str  # The pybtex style
    list_: str  # List type ('citation', 'bullet', 'enumerated')
    enumtype: str  # Enumeration type for enumerated lists
    start: int  # Start value for enumerated lists
    labelprefix: str  # String prefix for pybtex labels
    keyprefix: str  # String prefix for citation keys
    filter_: ast.AST  # Parsed filter expression
    citation_nodes: Dict[str, docutils.nodes.Element]  # Citation nodes by key
    keys: List[str]  # Keys listed as directive content

See :cite:t:`smith2020` for details on the methodology.
Recent studies :cite:p:`jones2019,brown2021` support this approach.

.. bibliography::

.. bibliography::
   :filter: cited and author % "Smith"
   :style: plain

.. bibliography::
   :list: enumerated
   :enumtype: upperroman
   :start: 1

.. bibliography:: methods.bib
   :keyprefix: method-
   :labelprefix: M

.. bibliography::
   :filter: cited and (author % "Smith" or year >= 2020) and type != "misc"