sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

Remove the recommendation about the bundled package

Open AA-Turner opened this issue 1 year ago • 2 comments

I think we should just remove the recommendation about the bundled package and rather suggest using pip in the first place.

Originally posted by @picnixz in https://github.com/sphinx-doc/sphinx/issues/12239#issuecomment-2058509129

AA-Turner avatar Apr 24 '24 06:04 AA-Turner

I personally think we should recommend virtualenv + pip in the first place; at least, we won't have any surprises (or there should be none!) @n-peugnet do you follow me for that call?

picnixz avatar Apr 24 '24 07:04 picnixz

IMO virtualenv + pip is a safe and portable default that would work as expected everywhere. The virtualenv part should be mandatory in the install instructions instead of recommended afterwards currently. The README should also be updated, maybe as a link to the installation page?

Another possibility would be to recommend pipx as suggested in the pip install warning. I'm not used to this tool but is seems like a fine way to install python CLI tools with dependency isolation.

I don't think the recommendation to use system packages should be removed. For most of the people this is probably the easiest way to install Sphinx, but maybe a warning should be added that mixing user installed pip and system packages can cause issues?

n-peugnet avatar Apr 25 '24 08:04 n-peugnet

Is this sufficiently addressed through #12458?

timhoffm avatar Jun 25 '24 10:06 timhoffm

Let's say yes cheers, and can always re-open if necessary

chrisjsewell avatar Jun 25 '24 10:06 chrisjsewell