Merge remote-tracking branch 'upstream/main' into finish-2193

Author: jeromedockes

doc/Makefile

@@ -28,25 +28,47 @@ html:
 	# the embedding of images more robust
 	rm -rf $(BUILDDIR)/html/_images
 	#rm -rf _build/doctrees/
-	SKB_TABLE_REPORT_VERBOSITY=0 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	SKB_TABLE_REPORT_VERBOSITY=0 $(SPHINXBUILD)  -D markdown_uri_doc_suffix="html.md" -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	# Build markdown sources so llms.txt links point to .md files
+	SKB_TABLE_REPORT_VERBOSITY=0 $(SPHINXBUILD) -D markdown_uri_doc_suffix="html.md" -b markdown $(ALLSPHINXOPTS) $(BUILDDIR)/markdown
+	cp -r $(BUILDDIR)/markdown/. $(BUILDDIR)/html/_sources/
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 html-noplot:
-	SKB_TABLE_REPORT_VERBOSITY=0 $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	SKB_TABLE_REPORT_VERBOSITY=0 SKIP_JUPYTERLITE=1 $(SPHINXBUILD) -D markdown_uri_doc_suffix="html.md" -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	# Build markdown sources so llms.txt links point to .md files
+	SKB_TABLE_REPORT_VERBOSITY=0 SKIP_JUPYTERLITE=1 $(SPHINXBUILD) -D markdown_uri_doc_suffix="html.md" -D plot_gallery=0 -b markdown $(ALLSPHINXOPTS) $(BUILDDIR)/markdown
+	cp -r $(BUILDDIR)/markdown/. $(BUILDDIR)/html/_sources/
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+html-quick:
+	# Only build the HTML pages, skipping the markdown build and copying of sources
+	SKB_TABLE_REPORT_VERBOSITY=0 SKIP_JUPYTERLITE=1 $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	SKB_TABLE_REPORT_VERBOSITY=0 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Linkcheck finished. Results are in $(BUILDDIR)/linkcheck."
 
 linkcheck-noplot:
-	$(SPHINXBUILD) -D plot_gallery=0 -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck-noplot
+	SKB_TABLE_REPORT_VERBOSITY=0 SKIP_JUPYTERLITE=1 $(SPHINXBUILD) -D plot_gallery=0 -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck-noplot
 	@echo
 	@echo "Linkcheck (no plot) finished. Results are in $(BUILDDIR)/linkcheck-noplot."
 
+markdown:
+	SKB_TABLE_REPORT_VERBOSITY=0 $(SPHINXBUILD) -b markdown $(ALLSPHINXOPTS) $(BUILDDIR)/markdown
+	@echo
+	@echo "Markdown build finished. The markdown files are in $(BUILDDIR)/markdown."
+
+markdown-noplot:
+	SKB_TABLE_REPORT_VERBOSITY=0 SKIP_JUPYTERLITE=1 $(SPHINXBUILD) -D plot_gallery=0 -b markdown $(ALLSPHINXOPTS) $(BUILDDIR)/markdown
+	@echo
+	@echo "Markdown build (no plot) finished. The markdown files are in $(BUILDDIR)/markdown."
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

doc/conf.py

@@ -24,6 +24,21 @@
 
 import jinja2
 
+# -- Copy files for docs --------------------------------------------------
+#
+# We avoid duplicating the information, but we do not use symlinks to be
+# able to build the docs on Windows
+shutil.copyfile("../RELEASE_PROCESS.rst", "RELEASE_PROCESS.rst")
+shutil.copyfile("../CHANGES.rst", "CHANGES.rst")
+shutil.copyfile("../CONTRIBUTING.rst", "CONTRIBUTING.rst")
+
+# Allow skipping jupyterlite to speed up builds (e.g. html-noplot)
+_SKIP_JUPYTERLITE = os.environ.get("SKIP_JUPYTERLITE", "").strip() in (
+    "1",
+    "true",
+    "yes",
+)
+
 # Generate the table report html file for the homepage
 sys.path.append(os.path.relpath("."))
 from data_ops_report import create_data_ops_report
@@ -43,14 +58,6 @@
 from github_link import make_linkcode_resolve
 from sphinx_gallery.notebook import add_code_cell, add_markdown_cell
 
-# -- Copy files for docs --------------------------------------------------
-#
-# We avoid duplicating the information, but we do not use symlinks to be
-# able to build the docs on Windows
-shutil.copyfile("../RELEASE_PROCESS.rst", "RELEASE_PROCESS.rst")
-shutil.copyfile("../CHANGES.rst", "CHANGES.rst")
-shutil.copyfile("../CONTRIBUTING.rst", "CONTRIBUTING.rst")
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -76,27 +83,36 @@
     "sphinx_copybutton",
     "sphinx_gallery.gen_gallery",
     "autoshortsummary",
+    "sphinx_llms_txt",
+    "sphinx_markdown_builder",
 ]
 
+# -- sphinx-llms-txt configuration -------------------------------------------
+# Link to Markdown sources in _sources/ (generated by the markdown builder).
+llms_txt_uri_template = "{base_url}_sources/{docname}.md"
+
 try:
     import sphinxext.opengraph  # noqa
 
     extensions.append("sphinxext.opengraph")
 except ImportError:
     print("ERROR: sphinxext.opengraph import failed")
 
-try:
-    import jupyterlite_sphinx  # noqa: F401
-
-    extensions.append("jupyterlite_sphinx")
-    with_jupyterlite = True
-except ImportError:
-    # In some cases we don't want to require jupyterlite_sphinx to be installed,
-    # e.g. the doc-min-dependencies build
-    warnings.warn(
-        "jupyterlite_sphinx is not installed, you need to install it "
-        "if you want JupyterLite links to appear in each example"
-    )
+if not _SKIP_JUPYTERLITE:
+    try:
+        import jupyterlite_sphinx  # noqa: F401
+
+        extensions.append("jupyterlite_sphinx")
+        with_jupyterlite = True
+    except ImportError:
+        # In some cases we don't want to require jupyterlite_sphinx to be installed,
+        # e.g. the doc-min-dependencies build
+        warnings.warn(
+            "jupyterlite_sphinx is not installed, you need to install it "
+            "if you want JupyterLite links to appear in each example"
+        )
+        with_jupyterlite = False
+else:
     with_jupyterlite = False
 
 import sphinx_autosummary_accessors

pixi.lock

@@ -63,6 +63,8 @@ dev = [
   "sphinx-copybutton",
   "sphinx-gallery",
   "sphinxext-opengraph",
+  "sphinx-llms-txt",
+  "sphinx-markdown-builder",
   "sphinx-autosummary-accessors",
   "statsmodels",
 
@@ -124,6 +126,8 @@ sphinx-gallery = "*"
 sphinxext-opengraph = "*"
 sphinx-autosummary-accessors = ">=2025.3.1,<2026"
 sphinx-sitemap = "*"
+sphinx-llms-txt = "*"
+sphinx-markdown-builder = "*"
 statsmodels = "*"
 optuna = "*"
 skorch = "*"
@@ -221,7 +225,8 @@ python = "~=3.14.0"
 
 [tool.pixi.feature.doc.tasks]
 build-doc = { cmd = "make html", cwd = "doc" }
-build-doc-quick = { cmd = "make html-noplot", cwd = "doc" }
+build-doc-no-plot = { cmd = "make html-no-plot", cwd = "doc" }
+build-doc-quick = { cmd = "make html-quick", cwd = "doc" }
 clean-doc = { cmd = "make clean", cwd = "doc" }
 linkcheck = { cmd = "make linkcheck", cwd = "doc" }
 linkcheck-quick = { cmd = "make linkcheck-noplot", cwd = "doc" }
@@ -278,6 +283,7 @@ exclude = [
   "dist",
   "doc/_build",
   "doc/auto_examples",
+  "skrub/_docs/*.py",
   "build",
   "pixi.lock",
 ]
@@ -364,6 +370,7 @@ xfail_strict = true
 addopts = ["--doctest-modules", "--strict-config", "--strict-markers"]
 doctest_optionflags = "NORMALIZE_WHITESPACE ELLIPSIS"
 
+
 [tool.codespell]
 # Ref: https://github.com/codespell-project/codespell#using-a-config-file
 skip = '.git*,*.svg,package-lock.json,*.lock,*.css,*-min.*,pyproject.toml'