Skip to content

Commit 20eebba

Browse files
lfiaschilfiaschi
committed
Adds fast build mode for documentation
Implements a fast build mode for the documentation to speed up development. This mode skips notebook execution and heavy API generation, significantly reducing build time. Adds Makefile targets for fast builds with different configurations (skipping notebooks, API generation, or both). Also adds a .gitignore rule to exclude the jupyter cache directory.
1 parent 9c429ed commit 20eebba

File tree

3 files changed

+119
-5
lines changed

3 files changed

+119
-5
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ docs/build/
8080
docs/gettext/
8181
docs/jupyter_execute/
8282
docs/source/api/generated/
83+
docs/source/.jupyter_cache/
8384

8485
# PyBuilder
8586
target/

‎Makefile‎

Lines changed: 46 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ PACKAGE_DIR = pymc_marketing
88
# COMMANDS #
99
#################################################################################
1010

11-
.PHONY: init lint check_lint format check_format test html cleandocs run_notebooks uml help
11+
.PHONY: init lint check_lint format check_format test html fasthtml cleandocs run_notebooks uml help
1212

1313
init: ## Install the package in editable mode
1414
python3 -m pip install -e .
@@ -35,13 +35,56 @@ test: ## Install test dependencies and run tests
3535
pip install .[test]
3636
pytest
3737

38-
html: ## Install documentation dependencies and build HTML docs
38+
html: ## Install documentation dependencies and build HTML docs (full build)
3939
pip install .[docs]
4040
python scripts/generate_gallery.py
4141
sphinx-build docs/source docs/build -b html
4242

43+
fasthtml: ## Build HTML docs in FAST mode (skip notebooks and heavy API, ~30-60 sec)
44+
@echo "======================================================================"
45+
@echo "⚡ FAST BUILD MODE - Development Documentation Build"
46+
@echo "======================================================================"
47+
@echo "Building documentation without notebooks and API generation..."
48+
@echo "For full build with all notebooks, use: make html"
49+
@echo "======================================================================"
50+
pip install .[docs]
51+
python scripts/generate_gallery.py
52+
PYMC_MARKETING_FAST_DOCS=1 sphinx-build docs/source docs/build -b html
53+
@echo "======================================================================"
54+
@echo "✓ Fast build complete! Open docs/build/index.html"
55+
@echo "======================================================================"
56+
57+
fasthtml-nb: ## Build HTML docs skipping only notebooks (API included)
58+
@echo "======================================================================"
59+
@echo "⚡ PARTIAL FAST BUILD - Skipping Notebooks Only"
60+
@echo "======================================================================"
61+
pip install .[docs]
62+
python scripts/generate_gallery.py
63+
SKIP_NOTEBOOKS=1 sphinx-build docs/source docs/build -b html
64+
@echo "======================================================================"
65+
@echo "✓ Build complete (notebooks skipped)!"
66+
@echo "======================================================================"
67+
68+
fasthtml-api: ## Build HTML docs skipping only API generation (notebooks included)
69+
@echo "======================================================================"
70+
@echo "⚡ PARTIAL FAST BUILD - Skipping API Generation Only"
71+
@echo "======================================================================"
72+
pip install .[docs]
73+
python scripts/generate_gallery.py
74+
SKIP_API_GENERATION=1 sphinx-build docs/source docs/build -b html
75+
@echo "======================================================================"
76+
@echo "✓ Build complete (API generation skipped)!"
77+
@echo "======================================================================"
78+
4379
cleandocs: ## Clean the documentation build directories
44-
rm -r "docs/build" "docs/jupyter_execute" "docs/source/api/generated"
80+
@echo "Cleaning documentation build artifacts..."
81+
rm -rf docs/build docs/jupyter_execute docs/source/api/generated docs/source/.jupyter_cache
82+
@echo "✓ Documentation directories cleaned!"
83+
84+
cleancache: ## Clean only the jupyter cache (keeps built docs)
85+
@echo "Cleaning Jupyter notebook cache..."
86+
rm -rf docs/source/.jupyter_cache docs/jupyter_execute
87+
@echo "✓ Jupyter cache cleaned!"
4588

4689
run_notebooks: ## Run Jupyter notebooks
4790
python scripts/run_notebooks/runner.py

‎docs/source/conf.py‎

Lines changed: 72 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,35 @@
11
#!/usr/bin/env python3
22
"""Sphinx configuration for PyMC-Marketing Docs."""
33

4+
import multiprocessing
45
import os
56

67
import pymc_marketing # isort:skip
78

9+
# -- Fast Build Mode Configuration ----------------------------------------
10+
# Set environment variables to speed up builds during development:
11+
# - PYMC_MARKETING_FAST_DOCS=1: Skip notebooks and heavy API generation
12+
# - SKIP_NOTEBOOKS=1: Skip notebook execution only
13+
# - SKIP_API_GENERATION=1: Skip API documentation generation only
14+
15+
FAST_DOCS = os.environ.get("PYMC_MARKETING_FAST_DOCS", "0") == "1"
16+
SKIP_NOTEBOOKS = os.environ.get("SKIP_NOTEBOOKS", "0") == "1" or FAST_DOCS
17+
SKIP_API_GENERATION = os.environ.get("SKIP_API_GENERATION", "0") == "1" or FAST_DOCS
18+
19+
if FAST_DOCS:
20+
print("=" * 70)
21+
print("FAST BUILD MODE ENABLED")
22+
print(" - Notebooks: SKIPPED")
23+
print(" - API Generation: SKIPPED")
24+
print(" - Build time: ~30-60 seconds")
25+
print("=" * 70)
26+
elif SKIP_NOTEBOOKS or SKIP_API_GENERATION:
27+
print("=" * 70)
28+
print("PARTIAL FAST BUILD MODE")
29+
print(f" - Notebooks: {'SKIPPED' if SKIP_NOTEBOOKS else 'ENABLED'}")
30+
print(f" - API Generation: {'SKIPPED' if SKIP_API_GENERATION else 'ENABLED'}")
31+
print("=" * 70)
32+
833
# -- General configuration ------------------------------------------------
934

1035
# General information about the project.
@@ -66,6 +91,21 @@
6691
"**.ipynb_checkpoints",
6792
]
6893

94+
# Fast build mode: Skip notebooks
95+
if SKIP_NOTEBOOKS:
96+
exclude_patterns.extend([
97+
"notebooks/**",
98+
"guide/benefits/model_deployment.ipynb",
99+
])
100+
print(" ⚡ Excluding all notebooks from build")
101+
102+
# Fast build mode: Skip API generation
103+
if SKIP_API_GENERATION:
104+
exclude_patterns.extend([
105+
"api/generated/**",
106+
])
107+
print(" ⚡ Excluding API documentation from build")
108+
69109
# The reST default role (used for this markup: `text`) to use for all documents.
70110
# This sets the behaviour to be the same as in markdown
71111
default_role = "code"
@@ -87,15 +127,41 @@
87127
remove_from_toctrees = ["**/classmethods/*"]
88128

89129
# myst config
90-
nb_execution_mode = "auto"
91-
nb_execution_excludepatterns = ["*.ipynb"]
130+
# Use cache mode for faster subsequent builds (only re-executes modified notebooks)
131+
# Use "off" in fast build mode to skip all notebook execution
132+
if SKIP_NOTEBOOKS:
133+
nb_execution_mode = "off"
134+
else:
135+
nb_execution_mode = "cache" # Changed from "auto" for better performance
136+
137+
nb_execution_cache_path = ".jupyter_cache" # Persistent cache directory
138+
nb_execution_timeout = 600 # 10 minutes per notebook
139+
nb_execution_allow_errors = False
140+
nb_execution_raise_on_error = True
141+
nb_execution_excludepatterns = [
142+
# Heavy notebooks that take too long - execute manually when needed
143+
"notebooks/mmm/mmm_case_study.ipynb",
144+
"notebooks/mmm/mmm_multidimensional_example.ipynb",
145+
"notebooks/mmm/mmm_tvp_example.ipynb",
146+
"notebooks/mmm/mmm_time_varying_media_example.ipynb",
147+
"notebooks/clv/dev/*.ipynb", # Development notebooks
148+
]
92149
nb_kernel_rgx_aliases = {".*": "python3"}
93150
myst_enable_extensions = ["colon_fence", "deflist", "dollarmath", "amsmath"]
94151
myst_heading_anchors = 0
95152

96153
# numpydoc and autodoc typehints config
97154
numpydoc_show_class_members = False
98155
numpydoc_xref_param_type = True
156+
157+
# Enable parallel builds for faster processing
158+
# Use all CPUs except one to keep system responsive
159+
autodoc_parallel = max(1, multiprocessing.cpu_count() - 1)
160+
161+
# Optimize autosummary generation
162+
autosummary_generate = True
163+
# Don't regenerate unchanged files (speeds up incremental builds)
164+
autosummary_generate_overwrite = False
99165
# fmt: off
100166
numpydoc_xref_ignore = {
101167
"of", "or", "optional", "default", "numeric", "type", "scalar", "1D", "2D", "3D", "nD", "array",
@@ -128,6 +194,10 @@
128194
"xarray": ("https://docs.xarray.dev/en/stable/", None),
129195
}
130196

197+
# Cache intersphinx inventories for faster builds
198+
intersphinx_cache_limit = 10 # Days to cache
199+
intersphinx_timeout = 30 # Seconds
200+
131201
# -- Options for HTML output ----------------------------------------------
132202

133203
# The theme to use for HTML and HTML Help pages. See the documentation for

0 commit comments

Comments
 (0)