DOC Add make.bat for building documentation on Windows by DCchoudhury15 · Pull Request #1963 · skrub-data/skrub

DCchoudhury15 · 2026-03-13T20:20:59Z

Description

Addresses #1720

Adds a make.bat script to the doc/ folder so that Windows users
can build the documentation without needing Make/Makefiles.

The script supports the same targets as the existing Makefile:

html - full build including gallery
html-noplot - fast build without running examples
linkcheck - check external links
linkcheck-noplot - check links without gallery
clean - remove all build output

Also updates CONTRIBUTING.rst to document the Windows equivalents
alongside the existing Linux/macOS commands.

Checklist

I have read the contributing guidelines
I have added tests that verify the bug fix
I have added an entry to CHANGES.rst describing the fix
My code follows the code style of this project
I have checked my code and corrected any misspellings

How Has This Been Tested?

Tested the equivalent make html-noplot build successfully on Linux
using pixi run build-doc-quick. The make.bat mirrors the same
Sphinx commands as the Makefile.

AI Disclosure

[] This PR contains AI-generated code
- [] I have tested the code generated in my PR
- [] I have read and understood every line that has been generated by the AI agent
- [] I can explain what the AI-generated code does

DCchoudhury15 · 2026-03-13T20:30:04Z

I was looking into the issue with Windows documentation builds and tried putting together a make.bat script for the doc/ folder. I attempted to map out the standard Makefile targets (like html, html-noplot, clean, etc.) and also added the Windows equivalents to CONTRIBUTING.rst.

I do have a quick question about testing this, though. Since I'm developing strictly on Linux right now, I don't actually have a local Windows environment to run this batch script natively. I tried to mirror the existing logic as closely as possible, but I'm basically hoping the Windows CI pipeline will catch any batch syntax quirks I might have missed. Does this approach work for this issue? I'll keep a close eye on the action logs and push fixes if the CI complains, but let me know if I should be handling this differently or if I missed any specific cache folders in the clean target!

rcap107 · 2026-03-14T17:57:48Z

Hi @DCchoudhury15, thanks for the PR. The CI is unlikely to spot any issues with the file because the docs are built with the regular makefile and the test matrix is only checking for the actual test suite.

I think there isn't an alternative to doing it the manual way and try to run it somehow on a machine that runs Windows. I'll try to do that to review the file when I can.

DCchoudhury15 · 2026-03-14T20:02:55Z

Thanks for the clarification @rcap107! I'm going to set up a Windows VM
locally to test this properly and will report back with the results.
I'll push any fixes needed based on what I find.

rcap107 · 2026-03-19T10:39:43Z

Hi @DCchoudhury15, before merging this PR there should also be an update to the pyproject.toml file to add target specific commands. Pixi allows to do this using https://pixi.prefix.dev/latest/workspace/multi_platform_configuration/#activation

There should be a specific entry for building the documentation with the bat file if the platform is win64.

DCchoudhury15 · 2026-03-19T19:10:48Z

Hi @rcap107!

I tested the make.bat script on a real Windows 11 machine with Python 3.13.4, Sphinx 7.4.7, and Graphviz 14.1.3, and the core targets are working great. The help command lists everything correctly, and running html-noplot successfully built the docs with just the pre-existing warnings. I opened the generated index.html in the browser and everything rendered properly. The clean command correctly wiped the _build, auto_examples, and generated reference folders. I also ran linkcheck-noplot which passed fine, only catching broken links that were already there. I skipped the full html build just because it takes a long time, but since html-noplot passed cleanly i presume it should work exactly the same hopefully.

I also added the Windows specific pixi tasks to pyproject.toml under [tool.pixi.feature.doc.target.win-64.tasks]. I made sure to verify on Linux that the existing pixi doc commands still work fine after the change. I did run into one weird issue on Windows though. When running the pixi build-doc-quick command there, pixi still seemed to try and execute make instead of make.bat. I am not sure if my syntax is slightly off or if the base feature-level tasks are overriding the target-level ones. Do you know the right way to configure this override in pixi?

rcap107

Thanks a lot for the PR, I was also able to run the scripts on a windows machine.

I could not run the optuna example with build-doc, were you able to do so? If there is a simple fix for it, we could go for it, otherwise I think we can just proceed as is, given that the CI is running on linux anyway.

rcap107 · 2026-03-19T20:26:21Z

+if exist "%BUILDDIR%\" (
+    rmdir /q /s "%BUILDDIR%"
+    echo. Removed %BUILDDIR%\
+)
+if exist "auto_examples\" (
+    rmdir /q /s "auto_examples"
+    echo. Removed auto_examples\
+)
+if exist "generated\" (
+    rmdir /q /s "generated"
+    echo. Removed generated\
+)
+if exist "reference\generated\" (
+    rmdir /q /s "reference\generated"
+    echo. Removed reference\generated\
+)
+if exist "generated_for_index\" (
+    rmdir /q /s "generated_for_index"
+    echo. Removed generated_for_index\
+)
+if exist "reference\" (
+    for %%i in ("reference\*.rst") do del /q "%%i" 2>nul
+    echo. Removed reference\*.rst
+)
+goto end


I noticed that more files are being cleaned here than in the original makefile. That's good! Could you update the linux makefile to match?

rcap107 · 2026-03-19T20:28:09Z

+build-doc = { cmd = "make.bat html", cwd = "doc" }
+build-doc-quick = { cmd = "make.bat html-noplot", cwd = "doc" }
+clean-doc = { cmd = "make.bat clean", cwd = "doc" }
+linkcheck = { cmd = "make.bat linkcheck", cwd = "doc" }
+linkcheck-quick = { cmd = "make.bat linkcheck-noplot", cwd = "doc" }


This should fix the windows targets

Suggested change

build-doc = { cmd = "make.bat html", cwd = "doc" }

build-doc-quick = { cmd = "make.bat html-noplot", cwd = "doc" }

clean-doc = { cmd = "make.bat clean", cwd = "doc" }

linkcheck = { cmd = "make.bat linkcheck", cwd = "doc" }

linkcheck-quick = { cmd = "make.bat linkcheck-noplot", cwd = "doc" }

build-doc = { cmd = ".\\make.bat html", cwd = "doc" }

build-doc-quick = { cmd = ".\\make.bat html-noplot", cwd = "doc" }

clean-doc = { cmd = ".\\make.bat clean", cwd = "doc" }

linkcheck = { cmd = ".\\make.bat linkcheck", cwd = "doc" }

linkcheck-quick = { cmd = ".\\make.bat linkcheck-noplot", cwd = "doc" }

…-64 task path

DCchoudhury15 · 2026-03-20T06:16:21Z

Hi @rcap107!

I just pushed the updates for both of your suggestions. I changed the win-64 tasks in pyproject.toml to use .\\make.bat instead of just make.bat, and after testing on Windows, this completely fixed the issue. pixi run --environment doc build-doc-quick now correctly fires off .\make.bat html-noplot. I also updated the clean target in the Linux Makefile so it matches the Windows one perfectly, wiping out auto_examples/, generated/, generated_for_index/, and reference/generated/. I verified this on my Linux setup and everything clears out properly when running the pixi clean command now.

I ran the full make.bat html build to test that optuna example. Almost everything ran perfectly (17 out of 18 examples passed), but 1131_optuna_choices.py did fail with a WinError 1314 regarding missing privileges.

From looking at the traceback, it seems optuna tries to create a symlink for a file lock when search.fit(env) is called. I guess Windows blocks symlink creation unless you have admin rights or Developer Mode enabled? Since this seems to be a Windows-specific quirk with how optuna handles its storage backend and probably not an issue with our make.bat script, do you think we are good to just proceed as is? I imagine the Linux CI ran it without any issues since symlinks work out of the box there, but I would love to hear what you think!

Co-authored-by: Riccardo Cappuzzo <7548232+rcap107@users.noreply.github.com>

rcap107 · 2026-03-20T09:14:25Z

Hi @DCchoudhury15, thanks a lot for the fixes.

I ran the full make.bat html build to test that optuna example. Almost everything ran perfectly (17 out of 18 examples passed), but 1131_optuna_choices.py did fail with a WinError 1314 regarding missing privileges.

From looking at the traceback, it seems optuna tries to create a symlink for a file lock when search.fit(env) is called. I guess Windows blocks symlink creation unless you have admin rights or Developer Mode enabled? Since this seems to be a Windows-specific quirk with how optuna handles its storage backend and probably not an issue with our make.bat script, do you think we are good to just proceed as is? I imagine the Linux CI ran it without any issues since symlinks work out of the box there, but I would love to hear what you think!

Yes, that's the same problem that I saw. I think we can proceed as is, but I think there should be a mention of this problem in the contribution doc where the Windows command is explained, so that people that try to use it don't get surprising results. Something like

If you are working on Windows, building the example 1131 on Optuna may fail with a permission error, but the rest of the documentation build should run without problem. In that case, it's fine to ignore the problem if your contribution does not touch that particular example: the CI will build the example as normal in the PR.

That should help with avoiding some confusion.

I think the PR is pretty much done and is only missing a message like the one I wrote to avoid potential confusion for new contributors. I might leave it open for a few days to let other maintainers leave comments if needed, but I'll likely merge this at the start of next week.

DCchoudhury15 · 2026-03-20T10:12:06Z

Hi @rcap107, I've added the note to CONTRIBUTING.rst right after the make.bat html section. Let me know if the wording looks good or if you'd like any changes!

rcap107 · 2026-03-20T13:14:17Z

Hi @rcap107, I've added the note to CONTRIBUTING.rst right after the make.bat html section. Let me know if the wording looks good or if you'd like any changes!

Looks good to me, I think we can merge this after all. Thanks a lot for the help!

DOC Add make.bat for building documentation on Windows

08e830e

rcap107 linked an issue Mar 17, 2026 that may be closed by this pull request

BUG - Fix doc generation command so that it can run on Windows #1720

Closed

rcap107 added this to the Release 0.8.1 milestone Mar 18, 2026

DOC Add Windows-specific pixi tasks in pyproject.toml for doc build

105491f

rcap107 reviewed Mar 19, 2026

View reviewed changes

DCchoudhury15 force-pushed the fix-windows-doc-build branch from de11b9d to e307abf Compare March 20, 2026 05:07

DOC Sync clean targets between Makefile and make.bat and fix pixi win…

494abcc

…-64 task path

DCchoudhury15 force-pushed the fix-windows-doc-build branch from e307abf to 494abcc Compare March 20, 2026 05:11

rcap107 reviewed Mar 20, 2026

View reviewed changes

Comment thread pyproject.toml Outdated

Update pyproject.toml

89acf84

Co-authored-by: Riccardo Cappuzzo <7548232+rcap107@users.noreply.github.com>

DCchoudhury15 added 2 commits March 20, 2026 14:52

CI Retrigger CI checks

78d8cfd

DOC Add note about optuna Windows permission issue in CONTRIBUTING.rst

110c3ed

DOC Revert pixi.lock to main

35ff550

DCchoudhury15 force-pushed the fix-windows-doc-build branch from 50bedac to 35ff550 Compare March 20, 2026 10:24

rcap107 approved these changes Mar 20, 2026

View reviewed changes

rcap107 merged commit 734b110 into skrub-data:main Mar 20, 2026
29 checks passed

Conversation

DCchoudhury15 commented Mar 13, 2026

Description

Checklist

How Has This Been Tested?

AI Disclosure

Uh oh!

DCchoudhury15 commented Mar 13, 2026

Uh oh!

rcap107 commented Mar 14, 2026

Uh oh!

DCchoudhury15 commented Mar 14, 2026

Uh oh!

rcap107 commented Mar 19, 2026

Uh oh!

DCchoudhury15 commented Mar 19, 2026

Uh oh!

rcap107 left a comment

Choose a reason for hiding this comment

Uh oh!

rcap107 Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

rcap107 Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

DCchoudhury15 commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

rcap107 commented Mar 20, 2026

Uh oh!

DCchoudhury15 commented Mar 20, 2026

Uh oh!

rcap107 commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

DCchoudhury15 commented Mar 20, 2026 •

edited

Loading

rcap107 commented Mar 20, 2026 •

edited

Loading