113 lines
4.4 KiB
Python
113 lines
4.4 KiB
Python
# 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'],
|
|
# }
|