Sphinx has deprecated the setuptools integration, and we’ll remove it in Sphinx 7. If you’re using an up-to-date version of Sphinx you should be seeing deprecation warnings.
It sounds like partly what you’re looking for is a generic command runner interface in pyproject.toml - this has been discussed many times though elsewhere (I think it’s off topic for this thread).
A
And you’re correct.
Unlike setup.py-based interfaces, the new build-backend model creates a clear separation of concerns. If you want to build a wheel or sdist, you can do that. Anything else, that is outside of the scope. Even setup.py bassed interfaces had that to an extent, but the user had way too much flexibility to influence various things in all sorts ways to break that assumption. That’s both a good thing and a bad thing.
Now, you’re going to need to do any additional stuff via dedicated separate mechanisms for that. For Sphinx, that’s sphinx-build on the command line. If you want a single-command workflow for generating wheels/sdist and the docs, use a task runner like tox, or nox, or heck make to run the two commands needed here.
Okay. Thanks so much for the clarification. I’ve seen plenty of references to tox, but never anything that made me think, “Oh, that’s what I’ve been looking for” like your statement above!
Ah, yes, I think that hits the nail on the head. Coming from a working setuptools process that built the docs, I was expecting the new pyproject.toml system to encompass that ability. I finally see that it is much more narrow, and I should have a look into tox and friends.
Yes, I saw that in the Sphinx docs. What I didn’t find was an explanation of what the new way is. (BTW, I’m not seeing any warning with sphinx 5.0.2 when invoked from py setup.py build.)
Agreed. I am planning to make it a larger write-up first, and also add some details on what invocation of common tools like pip take which path though that flowchart. But if someone wants to take the diagram and description now and add it to the Packaging Guide, that’d be perfectly fine with me.
Yes, this is unfortunate. I agree that “build” is the step that does the things you mention, and “build system” typically means the system which drives that step. It’s hard to define “build system” precisely (also in the context of pure Python packages that don’t need configure/compile/etc.), but I’d say it’s the tool that consumes the build config files you write in your project: setup.py → setuptools, CMakelists.txt → CMake, meson.build → Meson.
The “build backend” which is invoked by the hook in pyproject.toml may be a part of the build system, or it may be some shim layer like scikit-build or meson-python.