Python Extension API

def setup(app):
    """
    Main theme setup function called by Sphinx.
    
    Parameters:
    - app: Sphinx application instance
    
    Returns:
    dict: Extension metadata with parallel_read_safe and parallel_write_safe flags
    
    Actions:
    - Validates Python 3+ and Sphinx 6+ requirements  
    - Registers theme with Sphinx via app.add_html_theme()
    - Sets up message catalogs for internationalization support
    - Configures jQuery dependency via sphinxcontrib-jquery extension
    - Connects event handlers for configuration validation and context extension
    - Sets permalink icon to FontAwesome link icon (\uf0c1)
    """

# Theme is automatically registered via entry point in setup.cfg:
# [options.entry_points]
# sphinx.html_themes = 
#     sphinx_rtd_theme = sphinx_rtd_theme

# In conf.py:
html_theme = 'sphinx_rtd_theme'

def get_html_theme_path():
    """
    Return list of HTML theme paths (deprecated).
    
    Returns:
    str: Absolute path to theme directory
    
    Status: Deprecated with warning message
    Note: Safe to remove calls to this function when defining html_theme_path
    """

def config_initiated(app, config):
    """
    Sphinx event handler for configuration validation.
    
    Parameters:
    - app: Sphinx application instance
    - config: Sphinx configuration object
    
    Validates and warns about deprecated options:
    - canonical_url (use html_baseurl from Sphinx instead)
    - analytics_id (use sphinxcontrib-googleanalytics extension instead)
    - analytics_anonymize_ip (use sphinxcontrib-googleanalytics extension instead)
    - extra_css_file (use html_css_files from Sphinx instead)
    """

def extend_html_context(app, pagename, templatename, context, doctree):
    """
    Sphinx event handler for extending template context.
    
    Parameters:
    - app: Sphinx application instance
    - pagename: Current page name being rendered
    - templatename: Name of template being rendered
    - context: Template context dictionary (modified in-place)
    - doctree: Document tree for current page
    
    Adds to context:
    - sphinx_version_info: Sphinx version tuple for template conditionals
    - READTHEDOCS: Boolean indicating Read the Docs environment
    - READTHEDOCS_*: All Read the Docs environment variables
    """

# Available in all templates after context extension:
{
    'sphinx_version_info': tuple,  # e.g. (7, 1, 2)
    'READTHEDOCS': bool,           # True if building on Read the Docs
    'READTHEDOCS_VERSION': str,    # RTD version identifier (if applicable)
    'READTHEDOCS_PROJECT': str,    # RTD project name (if applicable)
    'READTHEDOCS_LANGUAGE': str,   # RTD language code (if applicable)
    # ... additional READTHEDOCS_* variables as available
}

__version__ = "3.0.2"
__version_full__ = "3.0.2" 
logger = getLogger(__name__)  # Package logger instance

# Automatic registration via setup.cfg:
[options.entry_points]
sphinx.html_themes = 
    sphinx_rtd_theme = sphinx_rtd_theme

# In Sphinx conf.py - theme is automatically available
html_theme = 'sphinx_rtd_theme'

# Custom extension that uses theme functions
def my_setup(app):
    # Access theme path (though not typically needed)
    theme_path = sphinx_rtd_theme.get_html_theme_path()
    
    # The theme's setup function handles all necessary registration
    # No manual theme registration needed due to entry point
    
    return {'version': '1.0', 'parallel_read_safe': True}

# In Jinja2 templates, after context extension:
{% if READTHEDOCS %}
    <div class="rtd-environment">
        Building on Read the Docs: {{ READTHEDOCS_VERSION }}
    </div>
{% endif %}

{% if sphinx_version_info >= (7, 0, 0) %}
    <!-- Use Sphinx 7+ features -->
{% endif %}