# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html


# -- Styling: type hints ------------------------------------------------------
# There are several possible style combinations for rendering types, none of
# which are optimal in my view. The main switches are:
# 
# - Parameter type hints in the signature vs in the separate parameter list
# - Show type hints as plaintext vs rendered HTML elements
#
# The `sphinx_autodoc_typehints` extension enables more context-aware
# rendering, but it's often way too explicit (e.g., unwrapping type variables)
# and makes things difficult to read. It does, however, allow for automatic
# inclusion of default values, which is nice.
#
# I'd like type hints to be rendered in an inline code element, but that
# doesn't happen by default in either case unless you render them in the
# signature. This is sloppy, however, often just a jumbled mess or parameter
# names and types. The current preferred option is to just use the native
# `autodoc` settings for rendering type hints, leaving them out of the
# signature (for easy heading readability). Type hints in the parameter list
# are also as short as possible, not rendered crazily (by default this is in
# italics; not my favorite but it's what we have). No
# `sphinx_autodoc_typehints` needed at this point; you can toggle it if you
# want automatic default values or different formatting for type hints.


# -- Project information ------------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = "trainlib"
copyright = "2026, Sam Griesemer"
author = "Sam Griesemer"


# -- General configuration ----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    "sphinx.ext.autodoc",

    # enables a directive to be specified manually that gathers module/object
    # summary details in a table
    "sphinx.ext.autosummary",

    # allow viewing source in the HTML pages
    "sphinx.ext.viewcode",

    # only really applies to manual docs; docstrings still need RST-like
    "myst_parser",

    # enables Google-style docstring formats
    "sphinx.ext.napoleon",

    # external extension that allows arg types to be inferred by type hints;
    # without this, type hints show up inside method signatures as plaintext,
    # but when enabled they are pulled into the parameter/description block and
    # rendered as native nested markup. What's best for a given package may
    # vary.
    # "sphinx_autodoc_typehints",
]
autosummary_generate = True
autosummary_imported_members = True

# include __init__ definitions in autodoc
autodoc_default_options = {
    "special-members": "__init__",
}

templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]


# -- Options for autodoc ------------------------------------------------------
# class signatures show up only in __init__ rather than at the class header;
# generally cleaner, avoids redundancy
autodoc_class_signature = "separated"

# if `sphinx_autodoc_typehints` extension is enabled, this is redundant: type
# hints are rendered natively and already show up in the parameter block. If
# it's disabled, this setting will do the same job of moving the types to the
# parameter block, but it renders them in plaintext (with links to in-package
# type refs).
autodoc_typehints = "description"  # "signature"
autodoc_typehints_format = "short"
autodoc_preserve_defaults = True
autodoc_use_type_comments = False
python_use_unqualified_type_names = True

# push parameters to their own lines in the signature block
# python_maximum_signature_line_length = 60


# -- Options for autodoc_typehints --------------------------------------------
# always_use_bars_union = True  # always on for Python 3.14+
# typehints_defaults = "braces-after"  # render defaults in param block
# typehints_use_signature = False  # False is default; enable if wanted in sig
# always_document_param_types = True  # show types even when not in docstring


# -- Options for HTML output --------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "furo"  # "pydata_sphinx_theme"
html_static_path = ["_static"]

# html_sidebars = {
#    '**': ['/modules.html'],
# }