# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
# pylint: skip-file
import os
import os.path as osp
import sys
import zipfile
import guidata.config as gcfg
sys.path.insert(0, os.path.abspath(".."))
# Importing sigima to avoid re-enabling guidata validation mode
import sigima # noqa
import datalab
os.environ["DATALAB_DOC"] = "1"
# Turn off validation of guidata config
# (documentation build is not the right place for validation)
gcfg.set_validation_mode(gcfg.ValidationMode.DISABLED)
def compress_tutorials_data(app):
"""Compress tutorials data folders to zip files in doc/_download directory."""
docpath = osp.abspath(osp.dirname(__file__))
tutorials_path = osp.join(docpath, "..", "datalab", "data", "tutorials")
download_dir = osp.join(docpath, "_download")
if not osp.exists(tutorials_path):
print(f"Warning: tutorials directory not found: {tutorials_path}")
return
# Create download directory if it doesn't exist
os.makedirs(download_dir, exist_ok=True)
# Look for folders in tutorials directory
try:
for item in os.listdir(tutorials_path):
item_path = osp.join(tutorials_path, item)
if osp.isdir(item_path):
zip_filename = osp.join(download_dir, f"{item}.zip")
print(f"Compressing tutorial folder: {item} -> {zip_filename}")
# Create zip file
with zipfile.ZipFile(zip_filename, "w", zipfile.ZIP_DEFLATED) as zipf:
for root, dirs, files in os.walk(item_path):
for file in files:
file_path = osp.join(root, file)
arcname = osp.join(item, osp.relpath(file_path, item_path))
zipf.write(file_path, arcname)
print(f"Created: {zip_filename}")
except Exception as exc:
print(f"Warning: failed to compress tutorials: {exc}")
def setup(app):
"""Setup function for Sphinx."""
app.connect("builder-inited", compress_tutorials_data)
# Exclude outreach directory from LaTeX/PDF builds
def exclude_outreach_from_latex(app):
"""Exclude outreach directory from LaTeX builds to keep it HTML-only."""
if app.builder.format == "latex":
# Exclude the entire outreach directory for PDF builds
patterns_to_exclude = ["outreach/*"]
for pattern in patterns_to_exclude:
if pattern not in app.config.exclude_patterns:
app.config.exclude_patterns.append(pattern)
# Suppress warnings about excluded outreach documents during latex builds
warnings_to_suppress = ["toc.excluded", "ref.doc"]
for warning_type in warnings_to_suppress:
if warning_type not in app.config.suppress_warnings:
app.config.suppress_warnings.append(warning_type)
# Exclude detailed API documentation from gettext extraction, but keep api/index.rst
def exclude_api_from_gettext(app):
if app.builder.name == "gettext":
# Get all RST files in the api directory
api_rel_dir = "features/advanced/api"
api_dir = osp.join(app.srcdir, *api_rel_dir.split("/"))
if osp.exists(api_dir):
for filename in os.listdir(api_dir):
if filename.endswith(".rst") and filename != "index.rst":
# Remove .rst extension and add wildcard
pattern = f"{api_rel_dir}/{filename[:-4]}*"
if pattern not in app.config.exclude_patterns:
app.config.exclude_patterns.append(pattern)
# Also check subdirectories like api/gui/
for dirname in os.listdir(api_dir):
subdir_path = osp.join(api_dir, dirname)
if osp.isdir(subdir_path):
# Exclude entire subdirectories except their index files
pattern = f"{api_rel_dir}/{dirname}/*"
if pattern not in app.config.exclude_patterns:
app.config.exclude_patterns.append(pattern)
# Suppress warnings about excluded API documents during gettext builds
app.config.suppress_warnings.extend(["toc.excluded", "ref.doc"])
app.connect("builder-inited", exclude_outreach_from_latex)
app.connect("builder-inited", exclude_api_from_gettext)
# -- Project information -----------------------------------------------------
project = "DataLab"
author = ""
copyright = "2023, DataLab Platform Developers"
release = datalab.__version__
rst_prolog = f"""
.. |download_link1| raw:: html
DataLab {release} | Windows 7 SP1, 8, 10, 11
""" # noqa: E501
# -- General configuration ---------------------------------------------------
extensions = [
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon",
"sphinx.ext.mathjax",
"sphinx.ext.githubpages",
"sphinx.ext.viewcode",
"sphinx_sitemap",
"myst_parser",
"sphinx_design",
"sphinx_copybutton",
"guidata.dataset.autodoc",
]
templates_path = ["_templates"]
exclude_patterns = []
# -- Options for sitemap extension -------------------------------------------
html_baseurl = datalab.__homeurl__ # for sitemap extension
sitemap_locales = ["en", "fr"]
sitemap_filename = "../sitemap.xml"
# -- Options for HTML output -------------------------------------------------
html_theme = "pydata_sphinx_theme"
html_logo = "_static/DataLab-Title.svg"
html_title = project
html_favicon = "_static/favicon.ico"
html_show_sourcelink = False
templates_path = ["_templates"]
if "language=fr" in sys.argv:
ann = "DataLab a été présenté à SciPy 2024 🐍, PyData Paris 2024, OSXP 2024 et OSXP 2025 🚀 — En savoir plus" # noqa: E501
else:
ann = "DataLab has been presented at SciPy 2024 🐍, PyData Paris 2024, OSXP 2024, and OSXP 2025 🚀 — Learn more" # noqa: E501
html_theme_options = {
"show_toc_level": 2,
"github_url": "https://github.com/DataLab-Platform/DataLab/",
"logo": {
"text": f"v{datalab.__version__}",
},
"icon_links": [
{
"name": "PyPI",
"url": "https://pypi.org/project/datalab-platform",
"icon": "_static/pypi.svg",
"type": "local",
"attributes": {"target": "_blank"},
},
{
"name": "CODRA",
"url": "https://codra.net",
"icon": "_static/codra.png",
"type": "local",
"attributes": {"target": "_blank"},
},
],
"announcement": ann,
}
html_static_path = ["_static"]
# -- Options for LaTeX output ------------------------------------------------
latex_logo = "_static/DataLab-Frontpage.png"
# -- Options for sphinx-intl package -----------------------------------------
locale_dirs = ["locale/"] # path is example but recommended.
gettext_compact = False
gettext_location = False
# -- Options for autodoc extension -------------------------------------------
autodoc_default_options = {
"members": True,
"member-order": "bysource",
}
# -- Options for intersphinx extension ---------------------------------------
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
"qwt": ("https://pythonqwt.readthedocs.io/en/latest/", None),
"numpy": ("https://numpy.org/doc/stable/", None),
"scipy": ("https://docs.scipy.org/doc/scipy/", None),
"scikit-image": ("https://scikit-image.org/docs/stable/", None),
"h5py": ("https://docs.h5py.org/en/stable/", None),
"guidata": ("https://guidata.readthedocs.io/en/latest/", None),
"plotpy": ("https://plotpy.readthedocs.io/en/latest/", None),
}
# -- Latex macros for math in docstrings -------------------------------------
macros = {
"FFT": r"\operatorname{FFT}",
"PSD": r"\operatorname{PSD}",
"sgn": r"\operatorname{sgn}",
"sinc": r"\operatorname{sinc}",
"sawtooth": r"\operatorname{sawtooth}",
"erfc": r"\operatorname{erfc}",
"erf": r"\operatorname{erf}",
}
latex_elements = {
"preamble": r"""
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{mathrsfs}"""
+ "\n".join(f"\\newcommand{{\\{cmd}}}{{{defn}}}" for cmd, defn in macros.items()),
}
# -- MathJax configuration for HTML output -----------------------------------
mathjax3_config = {
"loader": {"load": ["[tex]/ams"]},
"tex": {
"macros": macros,
},
}