Update installation page #595
Conversation
✅ Deploy Preview for scipy-org ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Good stuff! Maybe it could be a good idea to mention the |
I think that would be okay, although maybe sufficient to add a notice to the SciPy bug report template. |
There was a problem hiding this comment.
Thanks all for the comments! I have addressed all feedback as follows:
- Removed section on Python Distributions. Talk only about conda-forge, not Anaconda defaults.
- Discerned primarily between environment-based and project-based workflows, rather than PyPI vs conda-forge. Marked environment-based as "the traditional workflow", project-based as "recommended for new users", and "system package managers" as "simplest" (but not recommended).
- Removed existing discussion of pip vs conda vs system vs source
- Linked to the external docs for all tools
Let me know what you think!
|
shall we give a week or so for any more comments here? This is ready from my side. |
There was a problem hiding this comment.
Thank you @lucascolley!
Overarching comment: think of the target audience—who will be reading this guide, and why? Further keep things as simple and straightforward as possible, reducing choices only to those absolutely necessary.
| {{< admonition hint >}} | ||
| The second command changes directory into the directory of your project. | ||
| {{< /admonition >}} |
There was a problem hiding this comment.
@jarrodmillman, I believe the linter is suggesting changes which would break the formatting.
There was a problem hiding this comment.
You could try something like
<!-- prettier-ignore-start -->
...
<!-- prettier-ignore-end -->
With some effort and goodwill - maybe a week to get something that has been adequately discussed and agreed? Although, as I said before, that might be harder here than elsewhere. Still, if we do move it elsewhere, and then come back with the result, is a week an acceptable timeframe?
Honestly, if we need something now now, then I can live with the Anaconda option - but I do think it needs at least a mention and a link to the terms of service. It seems to me it would be very easy for someone in a medium-sized company to install Anaconda without realizing they could become liable to the download fees, and it would be irresponsible of us to make that easier, given the ease with which we can help people avoid it. |
Would you be willing to open a PR yourself at that stage? I would prefer to limit the scope of my PR to the main changes I feel are important (mentioning static type stubs, mentioning
Yes, that was what I originally had in this PR. |
That sounds reasonable to me.
Would you consider restoring that? I think I must have missed the discussion. |
There was a problem hiding this comment.
The first thing you see now on the install page is the following tip:
If you click through to the beginner guide, you get three options. Firstly, a link out to https://jupyter.org/try-jupyter/lab/. Secondly, a slightly more concise version of the existing "Scientific Python Distributions" section, with links to Anaconda, WinPython and Pyzo. This includes the note:
Users in large, non-university institutions may want to read Anaconda’s helpful blog on “when is Anaconda free to use?”
Thirdly, python -m pip install scipy. However, this is accompanied with the warning:
You may see this recommended in tutorials or classes, but it is not recommended to install packages globally on your system. The recommended way to install SciPy with pip is to use a virtual environment - see Installing with pip.
and a link to the PyPA discussion of venvs for the interested reader.
For users who remain on the main installation guide, they are recommended the project-based workflows, with full instructions to get set up from scratch, and also given the option of environment-based workflows. The existing sections on system package managers and building from source are reproduced below. Then we get the section on installing with type stubs.
Please let me know if anyone sees any more blockers. I have also addressed @stefanv's concern regarding "what does a uv user need to do if they reboot their machine" in the uv section.
| [scipy-user-guide]: https://docs.scipy.org/doc/scipy/tutorial/ | ||
|
|
||
| <a name="distributions"></a> | ||
|
|
There was a problem hiding this comment.
Do they need any warnings here about losing their work if they clear their cache etc?
There was a problem hiding this comment.
not sure - suggestions welcome!
content/en/beginner-install.md
Outdated
|
|
||
| - [WinPython](https://winpython.github.io): Another free distribution | ||
| including scientific packages and the Spyder IDE; Windows only, but | ||
| more actively maintained and supports the latest Python 3 versions. |
There was a problem hiding this comment.
More actively maintained than Anaconda?
There was a problem hiding this comment.
it looks like that was originally in relation to Python(x, y) - see #259. I guess we just remove that part now.
There was a problem hiding this comment.
@CAM-Gerlach thought I'd ping in case you have any opinions on the Python Distributions section here! Hasn't been updated in a while...
There was a problem hiding this comment.
Thanks, @lucascolley, for addressing the concerns around a beginner workflow. With those changes, including Matthew's phrasing around Anaconda licensing, I'm +1 on merging.
|
|
||
| <a name="system-package-managers"></a> | ||
|
|
||
| ## Installing system-wide via a system package manager |
There was a problem hiding this comment.
Since these methods are so problematic, we could consider only keeping the first sentence (warning) and not giving individual instructions for Debian, Fedora, and macos here.
Optionally, we could then show the route I mentioned elsewhere, which works perfectly well: install Python via system and then just create a virtual env using python -m venv. Since this page is no longer the beginner guide, I think that should be acceptable?
The suggestion is not needed for this PR, but if it seems like a sensible suggestion I'm happy to make a follow-up PR in the future.
There was a problem hiding this comment.
Since these methods are so problematic, we could consider only keeping the first sentence (warning) and not giving individual instructions for Debian, Fedora, and macos here.
I would be happy with that, let's see what others think.
Optionally, we could then show the route I mentioned elsewhere, which works perfectly well: install Python via system and then just create a virtual env using python -m venv. Since this page is no longer the beginner guide, I think that should be acceptable?
How does that differ from https://deploy-preview-595--scipy-org.netlify.app/install/#installing-with-pip? Just installing Python with a system package manager rather than python.org? I said in another thread that I would be happy to remove the hyperlink to python.org, but I thought that listing out options for installing Python might be overkill.
The suggestion is not needed for this PR, but if it seems like a sensible suggestion I'm happy to make a follow-up PR in the future.
👍
| [this guide in the SciPy docs](https://scipy.github.io/devdocs/building/index.html). | ||
| [the building from source guide in the SciPy docs][building-docs]. | ||
|
|
||
| [building-docs]: https://scipy.github.io/devdocs/building/index.html |
There was a problem hiding this comment.
Given the default recommendation to use uv for projects, I was wondering whether, in the future, we should adjust the above page accordingly?
I presume it can be used the same way pip is for SciPy development, adding a third code tab with uv run python dev.py and uv pip for installing dependencies?
There was a problem hiding this comment.
Given the default recommendation to use uv for projects, I was wondering whether, in the future, we should adjust the above page accordingly?
Yep! Although for SciPy, given the compiler dependencies, Pixi will probably be our best bet. I already use https://github.com/rgommers/pixi-dev-scipystack for all of my SciPy development. Windows support for PyTorch and JAX on conda-forge is still maturing (though actively - conda-forge/pytorch-cpu-feedstock#231), but we may be able to use PyPI on Windows to fill some gaps if anyone needs it.
A third tab for uv is probably not so useful, since it's relatively obvious what to do by following along with the pip instructions, and you have to do the same setup of system deps.
I presume it can be used the same way pip is for SciPy development, adding a third code tab with uv run python dev.py and uv pip for installing dependencies?
All that to say that we could do something like this. Or we could make a new page instead of adding a new tab, since there is much less to explain when most of the work is already done in writing the Pixi manifest. We may want to wait until somebody wants to try to merge Pixi support into the main repo, though.
Also I plan to add a note about scipy-stubs to the building from source page after this is merged.
|
@jarrodmillman just pinging again to ask about the lint errors - do you know if there is a way to format indented admonitions in the theme which appeases the linter? |
|
any further comments, on the unresolved comments or otherwise? If not, let's merge this in a few days |
|
@lucascolley the paragraph following is also impacted by that last change |
|
thanks Stefan, addressed |
|
Thanks, Lucas! Sorry this got a bit more involved than anticipated |
I wouldn't want it to be boring :) thank you to all reviewers who gave their time here! |
|
Thanks Lucas! |
uvandpixias optionsdefaults(Update installation page #595 (comment))cc @rgommers @stefanv @jarrodmillman @tupui @jorenham