Is your feature request related to a problem? Please describe.
Sphinx currently injects a "magical" setup.py build_sphinx command into setuptools-based projects. While this is likely be useful for some user workflows, recently this has been a major source of confusion in the Python ecosystem, due to some folks who are repackaging a substantial number of open source Python packages.
These repackagers have assumed that all Python projects that use setuptools and Sphinx also use this integration -- which is not true. Most users are not aware of this integration and do not use it or support it. By making projects explicitly opt-in to this integration, it would help avoid such confusion and problems due to repackagers trying to build documentation using this integration and that not working -- since it's not a way that the specific project supports for building documentation (eg: if they use any non-setuptools build backend).
Further, this also puts setuptools in a uniquely priviledged position with Sphinx -- something that Python packaging tooling has been actively working to avoid and move away from (see pyproject.toml based builds, introduced in PEP 517 / PEP 518).
Describe the solution you'd like
Move the setuptools integration into a separate package on PyPI. We can also add it as an optional dependency of Sphinx (via the extras mechanism), so that users who want this can use sphinx[setuptools] in their requirements.txt or pip install invocations.
Describe alternatives you've considered
Not doing anything, which... works. 🤷🏽♂️
I think this is suboptimal though -- see https://github.com/search?q=build_sphinx+is%3Aissue&type=issues -- there are many issues filed on the premise that this integration means that projects should actively support this, which is a generally harmful suggestion to make IMO. These assumptions break down for non-setuptools-based projects as well.
Additional context
I guess, it's worth noting that a certain individual has been filed 100s of issues against various Python projects regarding this exact issue -- demanding that the entire ecosystem support this integration as a way to build their documentation (see the search above).
Is your feature request related to a problem? Please describe.
Sphinx currently injects a "magical"
setup.py build_sphinxcommand into setuptools-based projects. While this is likely be useful for some user workflows, recently this has been a major source of confusion in the Python ecosystem, due to some folks who are repackaging a substantial number of open source Python packages.These repackagers have assumed that all Python projects that use setuptools and Sphinx also use this integration -- which is not true. Most users are not aware of this integration and do not use it or support it. By making projects explicitly opt-in to this integration, it would help avoid such confusion and problems due to repackagers trying to build documentation using this integration and that not working -- since it's not a way that the specific project supports for building documentation (eg: if they use any non-setuptools build backend).
Further, this also puts setuptools in a uniquely priviledged position with Sphinx -- something that Python packaging tooling has been actively working to avoid and move away from (see pyproject.toml based builds, introduced in PEP 517 / PEP 518).
Describe the solution you'd like
Move the setuptools integration into a separate package on PyPI. We can also add it as an optional dependency of Sphinx (via the extras mechanism), so that users who want this can use
sphinx[setuptools]in their requirements.txt orpip installinvocations.Describe alternatives you've considered
Not doing anything, which... works. 🤷🏽♂️
I think this is suboptimal though -- see https://github.com/search?q=build_sphinx+is%3Aissue&type=issues -- there are many issues filed on the premise that this integration means that projects should actively support this, which is a generally harmful suggestion to make IMO. These assumptions break down for non-setuptools-based projects as well.
Additional context
I guess, it's worth noting that a certain individual has been filed 100s of issues against various Python projects regarding this exact issue -- demanding that the entire ecosystem support this integration as a way to build their documentation (see the search above).