conf.py

# 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

import pathlib
import datetime


curr_file_dir = pathlib.Path(__file__).parent.resolve()

project = "GiGL"
author = "Snap Inc"
copyright = f"{datetime.datetime.now().year}, {author}"

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


# https://www.sphinx-doc.org/en/master/usage/extensions/index.html
extensions = [
    "sphinx.ext.autodoc",  # Pull in documentation from docstrings
    "sphinx_autodoc_typehints",  # Use Python annotations for documenting acceptable argument and return types
    "sphinx.ext.napoleon",  # Support for Google style docstrings
    "sphinx.ext.viewcode",  # Add links to the source code
    "sphinx.ext.autosummary", # Generates function/method/attribute summary lists
    "autoapi.extension", # Generate API docs without need to import modules: https://sphinx-autoapi.readthedocs.io/en/latest/index.html
    "sphinx_design", # Needed by themes
    "myst_nb", # Support for rendering Jupyter Notebooks: https://myst-nb.readthedocs.io/en/v1.2.0/
    "sphinx_copybutton", # Support for copying code snippets: https://sphinx-copybutton.readthedocs.io/
]

autoapi_type = 'python'
autoapi_dirs = ['gigl', 'snapchat']
autoapi_root = "docs/api"
autoapi_ignore = [
    "*migrations*", # Default value: https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html#confval-autoapi_ignore
    "**/setup.py",
    "**/__pycache__/**",
    "**/tests/**",
    "**_pb2.py", # Ignore generated protobuf files; by doing this we force use the _pb2.pyi files - they are more parsable
]

autodoc_typehints = "description" # Show typehints as content of the function or method
autoapi_options = [ # For config options see: https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
    'members', # Display children of an object
    'undoc-members', # Display objects that have no docstring
    'show-inheritance', # Display a list of base classes below the class signature.
    'show-module-summary', # Include autosummary directives in generated module documentation.
    'imported-members' # Display imported objects from top level package or module
]
typehints_fully_qualified = True
typehints_document_rtype = True
autoapi_python_class_content = "both" # Include both class and module docstrings in the output
autoapi_member_order = "groupwise" # Group members by class, functions, properties, etc.


myst_enable_extensions = [
    "html_image", # Convert <img> tags in markdown files; https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#html-images
]

include_patterns = [
    "docs/**",
    "gigl/**",
    "snapchat/**",
    "snapchat/**",
    "index.rst",
    "examples/**",
]

autodoc_default_options = {
    # Generate automatic documentation for all members of the target module
    'members': True,
    # Generate automatic documentation for members of the target module that don’t have a docstring or doc-comment
    'undoc-members': True,
    # Insert the class’s base classes after the class signature
    'show-inheritance': True,
   # Generate automatic documentation for special members of the target module
    'special-members': '__init__',
    # Exclude the given names from the members to document
    'exclude-members': "__weakref__,__dict__,__module__,__class__,__abstractmethods__," +
        # Also ignoring unhelpful members generated by protoc for protobuf classes
        "DESCRIPTOR,KEY_FIELD_NUMBER,VALUE_FIELD_NUMBER,ClearField,ASSIGNER_ARGS_FIELD_NUMBER," +
        "ASSIGNER_CLS_PATH_FIELD_NUMBER,assigner_cls_path,ExperimentalFlagsEntry",
}
# autodoc_typehints = "description"

templates_path = [
    'gh_pages_source/_templates'
]
html_static_path = [
    'gh_pages_source/_static',
]

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "pydata_sphinx_theme" # https://pydata-sphinx-theme.readthedocs.io/en/stable/
# Disable showing the rst source link - its not useful, neither is it asthetically pleasing.
# We enable the edit button instead so the src code can be seen and edited conveniently; see use of use_edit_page_button below.
html_show_sourcelink = False # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html#view-source-link
html_logo = "docs/assets/images/gigl.png"
html_favicon = "docs/assets/images/favicon.ico"

html_theme_options = {
    # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/header-links.html#icon-links
    "icon_links": [
        {
            "name": "GitHub",
            "url": "https://github.com/Snapchat/GiGL",
            "icon": "fa-brands fa-github",
        }
    ],
    "logo": {
        "text": "GiGL",
        "image_dark": "docs/assets/images/gigl.png",
    },
    # Allow user to directly edit the documentation
    # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html#add-an-edit-button
    "use_edit_page_button": True,
    # Configure secondary sidebar - remove right sidebar from example pages
    "secondary_sidebar_items": {
        "**": ["page-toc", "edit-this-page", "sourcelink"],  # Default for all pages
        "docs/api/**": ["page-toc", "sourcelink"],  # Remove edit-this-page button from api pages, as they are auto-generated
    },
}

# Allow user to directly edit the documentation
# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html#github
html_context = {
    "github_user": "Snapchat",
    "github_repo": "GiGL",
    "github_version": "main",
    "doc_path": "/",
}

nb_execution_mode = "off"  # Disable execution of notebooks; we only want to render them as static content