Debian Codegraph @

doc/conf.py

raw
1 # Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
2
3 # pylint: skip-file
4
5 import os
6 import os.path as osp
7 import sys
8 import zipfile
9
10 import guidata.config as gcfg
11
12 sys.path.insert(0, os.path.abspath(".."))
13
14 # Importing sigima to avoid re-enabling guidata validation mode
15 import sigima # noqa
16
17 import datalab
18
19 os.environ["DATALAB_DOC"] = "1"
20
21 # Turn off validation of guidata config
22 # (documentation build is not the right place for validation)
23 gcfg.set_validation_mode(gcfg.ValidationMode.DISABLED)
24
25
26 def compress_tutorials_data(app):
27 """Compress tutorials data folders to zip files in doc/_download directory."""
28 docpath = osp.abspath(osp.dirname(__file__))
29 tutorials_path = osp.join(docpath, "..", "datalab", "data", "tutorials")
30 download_dir = osp.join(docpath, "_download")
31
32 if not osp.exists(tutorials_path):
33 print(f"Warning: tutorials directory not found: {tutorials_path}")
34 return
35
36 # Create download directory if it doesn't exist
37 os.makedirs(download_dir, exist_ok=True)
38
39 # Look for folders in tutorials directory
40 try:
41 for item in os.listdir(tutorials_path):
42 item_path = osp.join(tutorials_path, item)
43 if osp.isdir(item_path):
44 zip_filename = osp.join(download_dir, f"{item}.zip")
45 print(f"Compressing tutorial folder: {item} -> {zip_filename}")
46
47 # Create zip file
48 with zipfile.ZipFile(zip_filename, "w", zipfile.ZIP_DEFLATED) as zipf:
49 for root, dirs, files in os.walk(item_path):
50 for file in files:
51 file_path = osp.join(root, file)
52 arcname = osp.join(item, osp.relpath(file_path, item_path))
53 zipf.write(file_path, arcname)
54
55 print(f"Created: {zip_filename}")
56 except Exception as exc:
57 print(f"Warning: failed to compress tutorials: {exc}")
58
59
60 def setup(app):
61 """Setup function for Sphinx."""
62 app.connect("builder-inited", compress_tutorials_data)
63
64 # Exclude outreach directory from LaTeX/PDF builds
65 def exclude_outreach_from_latex(app):
66 """Exclude outreach directory from LaTeX builds to keep it HTML-only."""
67 if app.builder.format == "latex":
68 # Exclude the entire outreach directory for PDF builds
69 patterns_to_exclude = ["outreach/*"]
70 for pattern in patterns_to_exclude:
71 if pattern not in app.config.exclude_patterns:
72 app.config.exclude_patterns.append(pattern)
73 # Suppress warnings about excluded outreach documents during latex builds
74 warnings_to_suppress = ["toc.excluded", "ref.doc"]
75 for warning_type in warnings_to_suppress:
76 if warning_type not in app.config.suppress_warnings:
77 app.config.suppress_warnings.append(warning_type)
78
79 # Exclude detailed API documentation from gettext extraction, but keep api/index.rst
80 def exclude_api_from_gettext(app):
81 if app.builder.name == "gettext":
82 # Get all RST files in the api directory
83 api_rel_dir = "features/advanced/api"
84 api_dir = osp.join(app.srcdir, *api_rel_dir.split("/"))
85 if osp.exists(api_dir):
86 for filename in os.listdir(api_dir):
87 if filename.endswith(".rst") and filename != "index.rst":
88 # Remove .rst extension and add wildcard
89 pattern = f"{api_rel_dir}/{filename[:-4]}*"
90 if pattern not in app.config.exclude_patterns:
91 app.config.exclude_patterns.append(pattern)
92
93 # Also check subdirectories like api/gui/
94 for dirname in os.listdir(api_dir):
95 subdir_path = osp.join(api_dir, dirname)
96 if osp.isdir(subdir_path):
97 # Exclude entire subdirectories except their index files
98 pattern = f"{api_rel_dir}/{dirname}/*"
99 if pattern not in app.config.exclude_patterns:
100 app.config.exclude_patterns.append(pattern)
101
102 # Suppress warnings about excluded API documents during gettext builds
103 app.config.suppress_warnings.extend(["toc.excluded", "ref.doc"])
104
105 app.connect("builder-inited", exclude_outreach_from_latex)
106 app.connect("builder-inited", exclude_api_from_gettext)
107
108
109 # -- Project information -----------------------------------------------------
110
111 project = "DataLab"
112 author = ""
113 copyright = "2023, DataLab Platform Developers"
114 release = datalab.__version__
115 rst_prolog = f"""
116 .. |download_link1| raw:: html
117
118 <a href="https://github.com/DataLab-Platform/DataLab/releases/download/v{release}/DataLab-{release}.msi">DataLab {release} | Windows 7 SP1, 8, 10, 11</a>
119 """ # noqa: E501
120
121 # -- General configuration ---------------------------------------------------
122
123 extensions = [
124 "sphinx.ext.intersphinx",
125 "sphinx.ext.napoleon",
126 "sphinx.ext.mathjax",
127 "sphinx.ext.githubpages",
128 "sphinx.ext.viewcode",
129 "sphinx_sitemap",
130 "myst_parser",
131 "sphinx_design",
132 "sphinx_copybutton",
133 "guidata.dataset.autodoc",
134 ]
135 templates_path = ["_templates"]
136 exclude_patterns = []
137
138 # -- Options for sitemap extension -------------------------------------------
139 html_baseurl = datalab.__homeurl__ # for sitemap extension
140 sitemap_locales = ["en", "fr"]
141 sitemap_filename = "../sitemap.xml"
142
143 # -- Options for HTML output -------------------------------------------------
144 html_theme = "pydata_sphinx_theme"
145 html_logo = "_static/DataLab-Title.svg"
146 html_title = project
147 html_favicon = "_static/favicon.ico"
148 html_show_sourcelink = False
149 templates_path = ["_templates"]
150 if "language=fr" in sys.argv:
151 ann = "DataLab a été présenté à <a href='https://cfp.scipy.org/2024/talk/G3MC9L/'>SciPy 2024</a> 🐍, <a href='https://pretalx.com/pydata-paris-2024/talk/WTDVCC/'>PyData Paris 2024</a>, <a href='https://www.youtube.com/watch?v=lBEu-DeHyz0&list=PLJjbbmRgu6RqGMOhahm2iE6NUkIYIaEDK'>OSXP 2024</a> et <a href='https://www.youtube.com/watch?v=0D4ffBJIc5Q&list=PLJjbbmRgu6RoVze2tajiPe3zJB5muBcuC'>OSXP 2025</a> 🚀 — <a href='https://datalab-platform.com/fr/outreach/index.html'>En savoir plus</a>" # noqa: E501
152 else:
153 ann = "DataLab has been presented at <a href='https://cfp.scipy.org/2024/talk/G3MC9L/'>SciPy 2024</a> 🐍, <a href='https://pretalx.com/pydata-paris-2024/talk/WTDVCC/'>PyData Paris 2024</a>, <a href='https://www.opensource-experience.com/'>OSXP 2024</a>, and <a href='https://datalab-platform.com/en/outreach/osxp2025.html'>OSXP 2025</a> 🚀 — <a href='https://datalab-platform.com/en/outreach/index.html'>Learn more</a>" # noqa: E501
154 html_theme_options = {
155 "show_toc_level": 2,
156 "github_url": "https://github.com/DataLab-Platform/DataLab/",
157 "logo": {
158 "text": f"v{datalab.__version__}",
159 },
160 "icon_links": [
161 {
162 "name": "PyPI",
163 "url": "https://pypi.org/project/datalab-platform",
164 "icon": "_static/pypi.svg",
165 "type": "local",
166 "attributes": {"target": "_blank"},
167 },
168 {
169 "name": "CODRA",
170 "url": "https://codra.net",
171 "icon": "_static/codra.png",
172 "type": "local",
173 "attributes": {"target": "_blank"},
174 },
175 ],
176 "announcement": ann,
177 }
178 html_static_path = ["_static"]
179
180 # -- Options for LaTeX output ------------------------------------------------
181 latex_logo = "_static/DataLab-Frontpage.png"
182
183 # -- Options for sphinx-intl package -----------------------------------------
184 locale_dirs = ["locale/"] # path is example but recommended.
185 gettext_compact = False
186 gettext_location = False
187
188 # -- Options for autodoc extension -------------------------------------------
189 autodoc_default_options = {
190 "members": True,
191 "member-order": "bysource",
192 }
193
194 # -- Options for intersphinx extension ---------------------------------------
195 intersphinx_mapping = {
196 "python": ("https://docs.python.org/3", None),
197 "qwt": ("https://pythonqwt.readthedocs.io/en/latest/", None),
198 "numpy": ("https://numpy.org/doc/stable/", None),
199 "scipy": ("https://docs.scipy.org/doc/scipy/", None),
200 "scikit-image": ("https://scikit-image.org/docs/stable/", None),
201 "h5py": ("https://docs.h5py.org/en/stable/", None),
202 "guidata": ("https://guidata.readthedocs.io/en/latest/", None),
203 "plotpy": ("https://plotpy.readthedocs.io/en/latest/", None),
204 }
205
206 # -- Latex macros for math in docstrings -------------------------------------
207 macros = {
208 "FFT": r"\operatorname{FFT}",
209 "PSD": r"\operatorname{PSD}",
210 "sgn": r"\operatorname{sgn}",
211 "sinc": r"\operatorname{sinc}",
212 "sawtooth": r"\operatorname{sawtooth}",
213 "erfc": r"\operatorname{erfc}",
214 "erf": r"\operatorname{erf}",
215 }
216
217 latex_elements = {
218 "preamble": r"""
219 \usepackage{amsmath}
220 \usepackage{amssymb}
221 \usepackage{mathrsfs}"""
222 + "\n".join(f"\\newcommand{{\\{cmd}}}{{{defn}}}" for cmd, defn in macros.items()),
223 }
224
225 # -- MathJax configuration for HTML output -----------------------------------
226 mathjax3_config = {
227 "loader": {"load": ["[tex]/ams"]},
228 "tex": {
229 "macros": macros,
230 },
231 }