Implementation:Scikit learn contrib Imbalanced learn Sphinx Documentation Config

Property	Value
Implementation	Sphinx_Documentation_Config
Project	Scikit-learn-contrib Imbalanced-learn
Source File	doc/conf.py (lines 1-335)
Type	Build Configuration
Import	N/A (executed by Sphinx build system)
Theme	pydata_sphinx_theme

Overview

This implementation defines the Sphinx documentation build configuration for the imbalanced-learn project. The file doc/conf.py is executed by the Sphinx build system to configure all aspects of documentation generation, including extension loading, HTML theming, cross-project intersphinx mappings, gallery generation, source code linking, and output format settings for LaTeX, man pages, and Texinfo.

The configuration registers a set of eleven Sphinx extensions that collectively enable autodoc generation, NumPy-style docstring rendering, academic citation support, interactive example galleries, copy-to-clipboard buttons, and responsive design components. It also hooks into the builder-inited event to dynamically generate minimum dependency tables from scikit-learn metadata.

Code Reference

Full path: doc/conf.py

The file is structured as a standard Sphinx conf.py module, executed at build time with the working directory set to the doc/ directory.

Extensions Configuration

The following extensions are loaded via the extensions list:

Extension	Purpose
sphinx.ext.autodoc	Automatically generates API documentation from Python docstrings
sphinx.ext.autosummary	Creates summary tables for modules and classes
sphinx.ext.doctest	Tests code snippets embedded in documentation
sphinx.ext.intersphinx	Cross-references objects in external Sphinx documentation sets
sphinx.ext.linkcode	Adds "[source]" links pointing to GitHub source code
sphinxcontrib.bibtex	Renders academic citations from BibTeX files
numpydoc	Parses NumPy-style docstrings into structured documentation
sphinx_issues	Links GitHub issue and user references in changelogs
sphinx_gallery.gen_gallery	Auto-generates example galleries from Python scripts
sphinx_copybutton	Adds copy-to-clipboard buttons on code blocks
sphinx_design	Provides responsive design components (grids, cards, tabs)

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.doctest",
    "sphinx.ext.intersphinx",
    "sphinx.ext.linkcode",
    "sphinxcontrib.bibtex",
    "numpydoc",
    "sphinx_issues",
    "sphinx_gallery.gen_gallery",
    "sphinx_copybutton",
    "sphinx_design",
]

General Project Settings

The project metadata and general Sphinx settings are configured as follows:

project = "imbalanced-learn"
copyright = f"2014-{datetime.now().year}, The imbalanced-learn developers"

from imblearn import __version__
version = __version__
release = __version__

source_suffix = ".rst"
master_doc = "index"
default_role = "literal"
add_function_parentheses = False
pygments_style = "sphinx"
exclude_patterns = ["_build", "_templates"]

The version and release values are dynamically imported from the imblearn package, ensuring documentation version always matches the installed library version. The default_role is set to "literal", meaning backtick-quoted text in RST files renders as inline code by default.

HTML Theme Configuration

The documentation uses the pydata_sphinx_theme, which provides a consistent look across scientific Python projects.

html_theme = "pydata_sphinx_theme"
html_title = f"Version {version}"
html_favicon = "_static/img/favicon.ico"
html_logo = "_static/img/logo_wide.png"
html_style = "css/imbalanced-learn.css"

html_theme_options = {
    "external_links": [],
    "github_url": "https://github.com/scikit-learn-contrib/imbalanced-learn",
    "use_edit_page_button": True,
    "show_toc_level": 1,
    "logo": {
        "image_dark": (
            "https://imbalanced-learn.org/stable/_static/img/logo_wide_dark.png"
        )
    },
}

Key theme features:

• Edit page button is enabled via use_edit_page_button, linking to the GitHub source of each documentation page.
• Dark mode logo is specified separately for proper rendering on dark backgrounds.
• The GitHub repository URL is displayed in the navigation bar.
• The html_context dictionary configures the GitHub user, repo, branch (master), and doc path for edit links.

Autodoc and Numpydoc Options

autodoc_default_options = {
    "members": True,
    "inherited-members": True,
}

autosummary_generate = True
numpydoc_show_class_members = False

• autodoc is configured to document all members including inherited ones by default.
• autosummary generation is enabled so stub files are created automatically.
• numpydoc class member listing is disabled to avoid duplicate rendering with autodoc.

Copybutton Configuration

copybutton_prompt_text = r">>> |\.\.\. "
copybutton_prompt_is_regexp = True

The copy button is configured to strip Python REPL prompts (>>> and ...) when copying code blocks, so users get clean executable code.

Bibtex Configuration

bibtex_bibfiles = ["bibtex/refs.bib"]

Academic references are loaded from bibtex/refs.bib and can be cited throughout the documentation using standard Sphinx citation roles.

Intersphinx Mappings

Intersphinx enables cross-referencing to external documentation for the following projects:

Key	Target URL
python	https://docs.python.org/{major_version}
numpy	https://numpy.org/doc/stable
scipy	https://docs.scipy.org/doc/scipy/reference
matplotlib	https://matplotlib.org/
pandas	https://pandas.pydata.org/pandas-docs/stable/
joblib	https://joblib.readthedocs.io/en/latest/
seaborn	https://seaborn.pydata.org/

intersphinx_mapping = {
    "python": (f"https://docs.python.org/{sys.version_info.major}", None),
    "numpy": ("https://numpy.org/doc/stable", None),
    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
    "matplotlib": ("https://matplotlib.org/", None),
    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
    "joblib": ("https://joblib.readthedocs.io/en/latest/", None),
    "seaborn": ("https://seaborn.pydata.org/", None),
}

The Python documentation URL dynamically uses the current major Python version. All mappings use None for the inventory location, meaning Sphinx fetches objects.inv from the root of each URL.

Sphinx-Gallery Configuration

plot_gallery = True

sphinx_gallery_conf = {
    "doc_module": "imblearn",
    "backreferences_dir": os.path.join("references/generated"),
    "show_memory": True,
    "reference_url": {"imblearn": None},
}

• doc_module is set to imblearn, so the gallery generator knows which module's examples to process.
• backreferences_dir stores generated backreference files in references/generated/.
• show_memory enables memory usage reporting for each gallery example.
• reference_url maps imblearn to None, indicating that cross-references within the project resolve locally.

Sphinx Issues Configuration

issues_uri = "https://github.com/scikit-learn-contrib/imbalanced-learn/issues/{issue}"
issues_github_path = "scikit-learn-contrib/imbalanced-learn"
issues_user_uri = "https://github.com/{user}"

This configures the sphinx_issues extension to link issue numbers and GitHub usernames in changelog entries directly to the corresponding GitHub pages.

Linkcode Resolver

linkcode_resolve = make_linkcode_resolve(
    "imblearn",
    (
        "https://github.com/scikit-learn-contrib/"
        "imbalanced-learn/blob/{revision}/"
        "{package}/{path}#L{lineno}"
    ),
)

The linkcode_resolve function is created by the helper make_linkcode_resolve (imported from sphinxext/github_link.py). It generates "[source]" links in the API documentation that point directly to the relevant line in the GitHub repository. The URL template includes placeholders for {revision} (git tag or commit), {package}, {path}, and {lineno}.

LaTeX Output Configuration

latex_documents = [
    (
        "index",
        "imbalanced-learn.tex",
        "imbalanced-learn Documentation",
        "The imbalanced-learn developers",
        "manual",
    ),
]

Configures a single LaTeX document output using the manual document class, starting from the index root document.

Man Page Output Configuration

man_pages = [
    (
        "index",
        "imbalanced-learn",
        "imbalanced-learn Documentation",
        ["The imbalanced-learn developers"],
        1,
    )
]

Generates a single man page in section 1 (general commands).

Texinfo Output Configuration

texinfo_documents = [
    (
        "index",
        "imbalanced-learn",
        "imbalanced-learn Documentation",
        "The imbalanced-learn developerss",
        "imbalanced-learn",
        "Toolbox for imbalanced dataset in machine learning.",
        "Miscellaneous",
    ),
]

Configures Texinfo output with the project categorized under Miscellaneous.

Dependency Generation Functions

Three functions handle dynamic generation of dependency tables at build time:

generate_min_dependency_table(app)

Generates an RST-formatted table of minimum dependency versions by reading from sklearn._min_dependencies.dependent_packages. The output is written to min_dependency_table.rst in the documentation root.

def generate_min_dependency_table(app):
    """Generate min dependency table for docs."""
    from sklearn._min_dependencies import dependent_packages

    package_header_len = max(len(package) for package in dependent_packages) + 4
    version_header_len = len("Minimum Version") + 4
    tags_header_len = max(len(tags) for _, tags in dependent_packages.values()) + 4

    output = StringIO()
    # ... builds RST table with = separators ...

    with (Path(".") / "min_dependency_table.rst").open("w") as f:
        f.write(output)

generate_min_dependency_substitutions(app)

Generates RST substitution definitions for minimum package versions (e.g., |NumpyMinVersion|), written to min_dependency_substitutions.rst.

def generate_min_dependency_substitutions(app):
    """Generate min dependency substitutions for docs."""
    from sklearn._min_dependencies import dependent_packages

    output = StringIO()
    for package, (version, _) in dependent_packages.items():
        package = package.capitalize()
        output.write(f".. |{package}MinVersion| replace:: {version}")
        output.write("\n")

    with (Path(".") / "min_dependency_substitutions.rst").open("w") as f:
        f.write(output)

setup(app)

The Sphinx setup hook registers both dependency generation functions to run on the builder-inited event, ensuring they execute before any documentation pages are processed.

def setup(app):
    app.connect("builder-inited", generate_min_dependency_table)
    app.connect("builder-inited", generate_min_dependency_substitutions)

Related Pages

• Principle:Scikit_learn_contrib_Imbalanced_learn_Sphinx_Documentation_Configuration
• Environment:Scikit_learn_contrib_Imbalanced_learn_Python_Scikit_learn