conf.py

import os
import sys

try:
    import gi

    gi.require_version("Gtk", "4.0")
    gi.require_version("Gdk", "4.0")
    gi.require_version("GObject", "2.0")
except ImportError:
    pass

sys.path.insert(0, os.path.abspath("../src"))
# 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

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

project = "Sugar-Toolkit-GTK4"
copyright = "2025, MostlyK"
author = "MostlyK"
release = "1.1.4"
version = "1.1.4"

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

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
    "sphinx.ext.autosummary",
    "sphinx.ext.coverage",
    "sphinx.ext.doctest",
    "sphinx.ext.todo",
    "autoapi.extension",
]

# AutoAPI Configuration - parses source files statically without importing
autoapi_type = "python"
autoapi_dirs = ["../src/sugar4"]
autoapi_root = "autoapi"
autoapi_ignore = ["*/__pycache__/*", "*/_version.py", "*/test_*.py", "*/*_test.py"]
autoapi_options = [
    "members",
    "undoc-members",
    "show-inheritance",
    "show-module-summary",
    "special-members",
    "imported-members",
]
autoapi_python_class_content = "both"
autoapi_member_order = "bysource"
autoapi_keep_files = True
autoapi_add_toctree_entry = False  # We'll add it manually in index.rst

# Autodoc configuration
autodoc_default_options = {
    "members": True,
    "member-order": "bysource",
    "special-members": "__init__",
    "undoc-members": True,
    "exclude-members": "__weakref__",
}

# Suppress warnings
suppress_warnings = [
    "toc.not_included",
    "ref.python",
    "ref.class",
    "ref.meth",
    "ref.attr",
    "ref.func",
    "autodoc.import_object",
    "docutils",
    "autoapi",
]

# Autodoc ignore certain patterns
autodoc_inherit_docstrings = True
autodoc_member_order = "bysource"

# Skip problematic modules
autodoc_mock_imports = [
    "gi",
    "gi.repository",
    "gi.repository.Gtk",
    "gi.repository.Gdk",
    "gi.repository.GdkPixbuf",
    "gi.repository.GObject",
    "gi.repository.GLib",
    "gi.repository.Gio",
    "gi.repository.Pango",
    "gi.repository.PangoCairo",
    "six",
    "six.moves",
    "decorator",
    "telepathy",
    "dbus",
    "SimpleHTTPServer",
    "socketserver",
    "sugar4",
    "cairo",
]

# Napoleon settings for Google/NumPy style docstrings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True

# Intersphinx configuration
intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "gtk": ("https://lazka.github.io/pgi-docs/Gtk-4.0/", None),
}

# Autosummary configuration
autosummary_generate = True
autosummary_imported_members = True

# Show module contents in toctree
toctree_collapse = False

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

# The master toctree document
master_doc = "index"

# The language for content autogenerated by Sphinx
language = "en"

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files
exclude_patterns = ["_build"]

# The name of the Pygments (syntax highlighting) style to use
pygments_style = "sphinx"

# A list of ignored prefixes for module index sorting
modindex_common_prefix = ["sugar4."]

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

html_theme = "sphinx_rtd_theme"
html_static_path = ["_static"]

# Theme options are theme-specific and customize the look and feel of a theme
html_theme_options = {
    "canonical_url": "https://sugar-toolkit-gtk4.readthedocs.io/",
    "analytics_id": "",
    "logo_only": False,
    "display_version": True,
    "prev_next_buttons_location": "bottom",
    "style_external_links": True,
    "vcs_pageview_mode": "blob",
    "style_nav_header_background": "#2980B9",
    # Toc options
    "collapse_navigation": False,  # Don't collapse by default
    "sticky_navigation": True,
    "navigation_depth": 6,  # Show more levels
    "includehidden": True,
    "titles_only": False,  # Show full contents, not just titles
}

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]

# Custom CSS files
html_css_files = [
    "custom.css",
]

# HTML title and meta
html_title = f"{project} v{release}"
html_short_title = project
html_show_sourcelink = True
html_show_sphinx = True
html_show_copyright = True

html_context = {
    "display_github": True,
    "github_user": "sugarlabs",
    "github_repo": "sugar-toolkit-gtk4",
    "github_version": "main",
    "conf_py_path": "/docs/",
    "source_suffix": ".rst",
}

# Custom sidebar templates, must be a dictionary that maps document names
# to template names
html_sidebars = {
    "**": [
        "relations.html",  # needs 'show_related': True theme option to display
        "searchbox.html",
    ]
}

# Output file base name for HTML help builder
htmlhelp_basename = "SugarToolkitGtk4doc"

# -- Options for manual page output ------------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (master_doc, "sugar-toolkit-gtk4", "Sugar Toolkit GTK4 Documentation", [author], 1)
]

# -- Options for Texinfo output ----------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (
        master_doc,
        "SugarToolkitGtk4",
        "Sugar Toolkit GTK4 Documentation",
        author,
        "SugarToolkitGtk4",
        "GTK4 port of the Sugar Toolkit for Python activities.",
        "Miscellaneous",
    ),
]

# -- Extension configuration -------------------------------------------------

# -- Options for todo extension ----------------------------------------------

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

# -- Options for sphinx-copybutton extension --------------------------------

# Configure copy button behavior
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
copybutton_prompt_is_regexp = True
copybutton_only_copy_prompt_lines = True
copybutton_remove_prompts = True

# -- Options for MyST parser extension --------------------------------------

# Enable MyST extensions
myst_enable_extensions = [
    "colon_fence",
    "deflist",
    "dollarmath",
    "fieldlist",
    "html_admonition",
    "html_image",
    "linkify",
    "replacements",
    "smartquotes",
    "strikethrough",
    "substitution",
    "tasklist",
]

# MyST configuration
myst_heading_anchors = 3
myst_url_schemes = ["http", "https", "mailto"]

# -- Options for sphinx-design extension -----------------------------------

# Enable design extensions for better layouts
sd_fontawesome_latex = True