MayraRuizT · Sep 1, 2026 · Aug 20, 2026 · Aug 24, 2026 · Aug 27, 2026
diff --git a/.gitignore b/.gitignore
@@ -10,3 +10,7 @@ results/
 .ipynb_checkpoints/
 *.pyc
 Results_PILOT/
+docs/build/
+docs/_build/
+docs/generated/
+nichesphere/
diff --git a/docs/Makefile b/docs/Makefile
@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
+SOURCEDIR     = .
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,104 @@
+/* --- Custom sidebar logo size --- */
+
+img[src*="logo.png"] {
+    max-height: 150px !important; /* Limits maximum image height */
+    height: 150px !important; /* Forces a fixed height of 140px */
+    width: auto !important; /* Maintains aspect ratio automatically */
+}
+
+
+
+
+/* --- Logo home page --- */
+
+/* Margin and spacing around the floating logo */
+img.logo-header {
+    background: none !important;
+    margin-left: 30px !important;
+    margin-bottom: 20px !important;
+    margin-top: -10px !important; /* Slightly aligns the top of the logo with the heading */
+}
+
+/* Improves text flow next to the logo */
+p {
+    text-align: justify;
+    line-height: 1.6 !important;
+}
+
+/* Clears floating alignment after the first block to prevent layout issues */
+.clear-float {
+    clear: both;
+}
+
+
+
+
+/* --- Styles for the nbgallery (Thumbnails in tutorial section) --- */
+
+/* Gallery container: uses flexbox to align cards */
+div.nbgallery {
+    display: flex !important;
+    flex-wrap: wrap !important;
+    gap: 15px !important;
+    margin-top: 20px !important;
+    margin-bottom: 25px !important;
+    align-items: stretch !important; /* IMPORTANT: Ensures all cards in the row have the same height */
+}
+
+/* Individual Card Formatting */
+.nbsphinx-gallery .sphx-glr-thumbcontainer,
+div.nbgallery > div {
+    border: 1px solid #e2e8f0 !important; /* Soft solid gray border */
+    border-style: solid !important;
+    border-radius: 50px !important;       /* Rounded corners */
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04) !important; /* Soft shadow */
+    background-color: #ffffff !important;
+    padding: 15px !important;
+    width: 210px !important;              /* Uniform width */
+    display: flex !important;
+    flex-direction: column !important;     /* Column layout: Image top, Text bottom */
+    justify-content: flex-start !important; /* Content starts at the top */
+    transition: transform 0.2s ease, box-shadow 0.2s ease !important;
+    height: auto !important;               /* IMPORTANT: Do not force fixed height */
+    box-sizing: border-box !important;
+}
+
+/* Hover effect in tutorial notebooks*/
+.nbsphinx-gallery .sphx-glr-thumbcontainer:hover,
+div.nbgallery > div:hover {
+    transform: translateY(-3px) !important;
+    box-shadow: 0 8px 16px rgba(0, 0, 0, 0.08) !important;
+    border-color: #cbd5e1 !important;
+}
+
+/* Image inside the card */
+.nbsphinx-gallery .sphx-glr-thumbcontainer img,
+div.nbgallery img {
+    max-height: 120px !important;
+    object-fit: contain !important;
+    margin: 0 auto !important;
+    display: block !important;
+    border-bottom: 1px solid #f1f5f9 !important; /* Divider line below image */
+    padding-bottom: 10px !important;
+    margin-bottom: 0 !important;               /* REMOVES margin that pushed text down */
+}
+
+/* Notebook Text/Title style */
+.nbsphinx-gallery a,
+div.nbgallery a,
+.nbsphinx-gallery .sphx-glr-thumbcontainer a {
+    color: var(--color-foreground-primary, currentColor) !important; /* Professional dark text color */
+    font-weight: 600 !important;
+    font-size: 0.9em !important;
+    line-height: 1.4 !important;
+    text-decoration: none !important;     /* Removes blue underline */
+    text-align: center !important;
+    margin-top: 10px !important;         /* Space between divider line and text */
+    display: block !important;
+    width: 100% !important;
+}
+
+.nbsphinx-gallery a:hover,
+div.nbgallery a:hover {
+    color: var(--color-brand-primary, #2563eb) !important;
+}
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,11 +1,8 @@
 API Reference
 =============
 
-.. toctree::
-   :maxdepth: 2
-
-   coloc
-   comm
-   tl
-   niche_stats
-   sankey
+.. include:: coloc.rst
+.. include:: comm.rst
+.. include:: tl.rst
+.. include:: niche_stats.rst
+.. include:: sankey.rst
diff --git a/docs/coloc.rst b/docs/coloc.rst
@@ -1,9 +1,24 @@
+.. custom label for :ref: on the home page 
+.. _api_coloc:
+
 coloc module
-=======================
+--------------
 
 Focused on differential co-localization
 
-.. automodule:: nichesphere.coloc
-   :members:
-   :undoc-members:
-   :show-inheritance:
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   ~nichesphere.coloc.OvsE_coloc_test
+   ~nichesphere.coloc.OvsE_coloc_test_adjPval
+   ~nichesphere.coloc.cellCatContained
+   ~nichesphere.coloc.colocNW
+   ~nichesphere.coloc.compute_sc_spatial_knn_coloc_matrix
+   ~nichesphere.coloc.compute_sc_spatial_radius_coloc_matrix
+   ~nichesphere.coloc.diffColoc_test
+   ~nichesphere.coloc.getColocProbs
+   ~nichesphere.coloc.reshapeColoc
+   ~nichesphere.coloc.spatialCTPlot
+   ~nichesphere.coloc.spatialNichePlot
+   ~nichesphere.coloc.spatialSingleCTPlot
diff --git a/docs/comm.rst b/docs/comm.rst
@@ -1,9 +1,21 @@
+.. custom label for :ref: on the home page 
+.. _api_comm:
+
 comm module
-=======================
+--------------
 
 Focused on differential communication
 
-.. automodule:: nichesphere.comm
-   :members:
-   :undoc-members:
-   :show-inheritance:
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   ~nichesphere.comm.calculate_LR_CT_pair_scores_dir
+   ~nichesphere.comm.catNW
+   ~nichesphere.comm.cellCatContained
+   ~nichesphere.comm.diffCcommStats
+   ~nichesphere.comm.equalizeScoresTable
+   ~nichesphere.comm.getDiffComm
+   ~nichesphere.comm.lr_ctPairScores_perCat_dir
+   ~nichesphere.comm.plotDiffCcommStatsHM
+   ~nichesphere.comm.unique
diff --git a/docs/conf.py b/docs/conf.py
@@ -23,19 +23,47 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx_rtd_theme', 'nbsphinx', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx']
-
+extensions = [
+    'sphinx.ext.autodoc', 
+    'sphinx.ext.napoleon', 
+    'sphinx_book_theme',
+    'nbsphinx', 
+    'sphinx.ext.autosummary',
+    'sphinxcontrib.bibtex', 
+    'sphinx.ext.intersphinx',
+    'sphinx_design']
+
+autosummary_generate = True # Auto-generates individual API doc pages from summary tables
 templates_path = ['_templates']
 exclude_patterns = []
 
 language = 'English'
 
+# -- BibTeX citation settings
+bibtex_bibfiles = ['references.bib']
+bibtex_default_style = 'alpha'
+
+# -- It hides the input/output prompt numbers (In [1]: / Out [1]:).
+nbsphinx_prolog = """
+.. raw:: html
+
+    <style>
+        div.nbinput.container div.prompt,
+        div.nboutput.container div.prompt,
+        span.prompt {
+            display: none !important;
+            min-width: 0 !important;
+            padding: 0 !important;
+        }
+    </style>
+"""
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-#import sphinx_rtd_theme
+#import sphinx_book_theme
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_book_theme'
 html_static_path = ['_static']
 
 # Path to the logo relative to the configuration directory
@@ -44,10 +72,25 @@
 # Ensure the static path is included so Sphinx finds the file
 html_static_path = ['_static']
 
-# (Optional) If you want ONLY the logo to show without the project name text
-html_theme_options = {
-    'logo_only': True,
-    'display_version': False,
-}
-
+# Link custom CSS (logo sizing and styling, located in '_static')
+html_css_files = [
+    "custom.css",
+]
 
+# Specific parameters passed directly to the 'sphinx_book_theme'.
+html_theme_options = {
+    # URL of the GitHub repository
+    "repository_url": "https://github.com/CostaLab/Nichesphere",
+    # GitHub button in the top navigation bar
+    "use_repository_button": True,
+    # Show a download button (e.g., PDF or Markdown/RST)
+    "use_download_button": True,
+    # Full-screen reading mode
+    "use_fullscreen_button": True,
+    # Collapse inactive subsections in the left sidebar to keep it tidy
+    "collapse_navbar": True,
+    # Set the maximum depth of heading levels (H1 to H4) shown in the right-hand page TOC
+    "show_toc_level": 4,
+    # Control how many navigation levels deep are automatically expanded in the left sidebar
+    "show_navbar_depth": 2,
+}
diff --git a/docs/generated/nichesphere.coloc.OvsE_coloc_test.rst b/docs/generated/nichesphere.coloc.OvsE_coloc_test.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.OvsE\_coloc\_test
+===================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: OvsE_coloc_test
diff --git a/docs/generated/nichesphere.coloc.OvsE_coloc_test_adjPval.rst b/docs/generated/nichesphere.coloc.OvsE_coloc_test_adjPval.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.OvsE\_coloc\_test\_adjPval
+============================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: OvsE_coloc_test_adjPval
diff --git a/docs/generated/nichesphere.coloc.cellCatContained.rst b/docs/generated/nichesphere.coloc.cellCatContained.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.cellCatContained
+==================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: cellCatContained
diff --git a/docs/generated/nichesphere.coloc.colocNW.rst b/docs/generated/nichesphere.coloc.colocNW.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.colocNW
+=========================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: colocNW
diff --git a/docs/generated/nichesphere.coloc.colocNW_old.rst b/docs/generated/nichesphere.coloc.colocNW_old.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.colocNW\_old
+==============================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: colocNW_old
diff --git a/docs/generated/nichesphere.coloc.compute_sc_spatial_knn_coloc_matrix.rst b/docs/generated/nichesphere.coloc.compute_sc_spatial_knn_coloc_matrix.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.compute\_sc\_spatial\_knn\_coloc\_matrix
+==========================================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: compute_sc_spatial_knn_coloc_matrix
diff --git a/docs/generated/nichesphere.coloc.compute_sc_spatial_radius_coloc_matrix.rst b/docs/generated/nichesphere.coloc.compute_sc_spatial_radius_coloc_matrix.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.compute\_sc\_spatial\_radius\_coloc\_matrix
+=============================================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: compute_sc_spatial_radius_coloc_matrix
diff --git a/docs/generated/nichesphere.coloc.diffColoc_test.rst b/docs/generated/nichesphere.coloc.diffColoc_test.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.diffColoc\_test
+=================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: diffColoc_test
diff --git a/docs/generated/nichesphere.coloc.getColocProbs.rst b/docs/generated/nichesphere.coloc.getColocProbs.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.getColocProbs
+===============================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: getColocProbs
diff --git a/docs/generated/nichesphere.coloc.reshapeColoc.rst b/docs/generated/nichesphere.coloc.reshapeColoc.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.reshapeColoc
+==============================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: reshapeColoc
diff --git a/docs/generated/nichesphere.coloc.spatialCTPlot.rst b/docs/generated/nichesphere.coloc.spatialCTPlot.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.spatialCTPlot
+===============================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: spatialCTPlot
diff --git a/docs/generated/nichesphere.coloc.spatialNichePlot.rst b/docs/generated/nichesphere.coloc.spatialNichePlot.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.spatialNichePlot
+==================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: spatialNichePlot
diff --git a/docs/generated/nichesphere.coloc.spatialSingleCTPlot.rst b/docs/generated/nichesphere.coloc.spatialSingleCTPlot.rst
@@ -0,0 +1,6 @@
+nichesphere.coloc.spatialSingleCTPlot
+=====================================
+
+.. currentmodule:: nichesphere.coloc
+
+.. autofunction:: spatialSingleCTPlot
diff --git a/docs/generated/nichesphere.comm.calculate_LR_CT_pair_scores_dir.rst b/docs/generated/nichesphere.comm.calculate_LR_CT_pair_scores_dir.rst
@@ -0,0 +1,6 @@
+nichesphere.comm.calculate\_LR\_CT\_pair\_scores\_dir
+=====================================================
+
+.. currentmodule:: nichesphere.comm
+
+.. autofunction:: calculate_LR_CT_pair_scores_dir