conf.py

# Configuration file for the Sphinx documentation builder.

# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------
import os
import sys
from datetime import datetime
from pathlib import Path
import re
from sphinx.ext import apidoc
import cell2net as cn

sys.path.insert(0, os.path.abspath("../src"))

HERE = Path(__file__).parent
sys.path.insert(0, str(HERE / "extensions"))

# -- Project information -----------------------------------------------------
project = "Cell2net"
author = "Zhijian Li"
copyright = f"{datetime.now():%Y}, {author}."

# The short X.Y.Z version (including .devXXXX, rcX, b1 suffixes if present)
version = re.sub(r"(\d+\.\d+.\d+)\.\d+(.*)", r"\1\2", cn.__version__)
version = re.sub(r"(\.dev\d+).*?$", r"\1", version)

# The full version, including alpha/beta/rc tags.
release = cn.__version__

# pyData/Sphinx-Theme version switcher
if ".dev" in version:
    switcher_version = "dev"
else:
    switcher_version = f"{version}"


print(
    f"Building documentation for Cell2net {release} (short version: {version}, switcher version: {switcher_version})"
)

bibtex_bibfiles = ["references.bib"]
templates_path = ["_templates"]
nitpicky = True  # Warn about broken links
needs_sphinx = "4.0"

html_context = {
    "display_github": True,  # Integrate GitHub
    "github_user": "pinellolab",
    "github_repo": "cell2net",
    "github_version": "main",
    "conf_py_path": "/docs/",
}

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings.
# They can be extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
    "myst_nb",
    "sphinx_copybutton",
    "sphinx.ext.autodoc",
    "sphinx.ext.intersphinx",
    "sphinx.ext.autosummary",
    "sphinx.ext.napoleon", # numpy / Google style docstrings
    "sphinxcontrib.bibtex",
    "sphinx_autodoc_typehints",
    "sphinx_tabs.tabs",
    "sphinx.ext.mathjax",
    "IPython.sphinxext.ipython_console_highlighting",
    "sphinxext.opengraph",
    *[p.stem for p in (HERE / "extensions").glob("*.py")],
]

autosummary_generate = True
autodoc_member_order = "bysource"
# default_role = "literal"
napoleon_google_docstring = False
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_use_rtype = True  # having a separate entry generally helps readability
napoleon_use_param = True
napoleon_custom_sections = [("Params", "Parameters")]
myst_heading_anchors = 6  # create anchors for h1-h6
myst_enable_extensions = [
    "amsmath",
    "colon_fence",
    "deflist",
    "dollarmath",
    "html_image",
    "html_admonition",
]
myst_url_schemes = ("http", "https", "mailto")
nb_output_stderr = "remove"
nb_execution_mode = "off"
nb_merge_streams = True
typehints_defaults = "braces"

source_suffix = {
    ".rst": "restructuredtext",
    ".ipynb": "myst-nb",
    ".myst": "myst-nb",
}

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
    "mudata": ("https://mudata.readthedocs.io/en/stable/", None),
    "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
    "numpy": ("https://numpy.org/doc/stable/", None),
    "pandas": ("https://pandas.pydata.org/docs/", None),
}

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]


# -- Options for HTML output -------------------------------------------------
html_theme = "pydata_sphinx_theme"
html_show_sphinx = False
html_show_sourcelink = False
html_static_path = ["_static"]
html_css_files = [
    "css/custom.css",
]

# Define the json_url for our version switcher.
json_url = "https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/switcher.json"

# Define the version we use for matching in the version switcher.
release = cn.__version__

html_theme_options = {
    "icon_links": [
        {
            "name": "GitHub",
            "url": "https://github.com/pinellolab/cell2net",
            "icon": "fa-brands fa-github",
        }
    ],
    #
    "use_edit_page_button": True,
    "show_toc_level": 1,
    "navbar_align": "left",
    "navbar_center": ["version-switcher", "navbar-nav"],
    "use_repository_button": True,
    "path_to_docs": "docs/",
    "navigation_with_keys": False,
    "switcher": {
        "version_match": switcher_version,
        "json_url": "https://raw.githubusercontent.com/pinellolab/cell2net/main/docs/_static/versions.json",
    },
}

pygments_style = "default"

nitpick_ignore = [
    # If building the documentation fails because of a missing link that is outside your control,
    # you can add an exception to this list.
    #     ("py:class", "igraph.Graph"),
]

# function to run sphinx-apidoc
def run_apidoc(app):
    here = os.path.dirname(__file__)
    src_dir = os.path.abspath(os.path.join(here, "../src/cell2net"))
    out_dir = os.path.join(here, "api")

    # sphinx-apidoc -o docs/api src/cell2net -f -e -M
    apidoc.main([
        "--force",
        "--separate",
        "--module-first",
        "-o", out_dir,
        src_dir,
    ])

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