Repository navigation
Consolidate Install Docs #17327
Description
Installation is documented in at least 4 places:
- users/installing
- contributing/retrieve latest version of source install
- FAQ/Installation
- https://github.com/matplotlib/matplotlib/blob/master/INSTALL.rst
which can lead to them being out of sync, as seen by the issues targeting only one page in the docs, and can make it harder for new users (especially new contributors) to figure out which instructions they're supposed to be following. I propose the docs get consolidated down to one installation page, the section from the FAQ be removed, and that the developer docs & install.rst should cross link to that install page.
In the process of consolidating the docs, the following issues should probably also at least be addressed:
- Update virtualenv + OSX + conda guide #6418 Update virtual env+osx+conda docs
- Document windows build using conda #8652 Windows build using conda
- Setting alpha on legend handle changes patch color #11702 Installing from source on windows
- Re-opening Definitive Docs for compilation on Windows. #7418 Definitive Docs for Compilation on Windows
- Improve dev installation documentation #14755 uninstall existing versions of matplotlib
- document where nightly wheels are published #9994 Document nightly wheels location
Activity
[-]Consoli[/-][+]Consolidate Install Docs [/+]r0cketr1kky commentedon May 12, 2020
Hi @story645 , I would like to take this up.
story645 commentedon May 12, 2020
go for it!
r0cketr1kky commentedon May 14, 2020
Do you want me to remove the entire
doc/faqfolder or onlydoc/faq/installing_faq.rst? I guess it's the latter but just wanted to confirm :)Another doubt: I need to remove all these 4 files addressed in this issue and include these in the canonical install page and include the contents of all these 4 pages right, keeping the home page links as the canonical install instructions?
story645 commentedon May 14, 2020
My suggestion is to consolidate everything in the the users/install page & maybe keep the existing files but replace the text with a link back to the install instructions.
r0cketr1kky commentedon May 14, 2020
Sounds like a plan. I'm on it :)
timhoffm commentedon May 17, 2020
I recommend to keep installation for development in the contribution docs. The two locations address different audiences and having a long page of installation instructions may be intimidating for a simple user (even though he might only need a fraction of the page).
Also "Installing for development" is not useful by itself. It needs to be done in context with cloning the repo and setting up a development env (virtualenv/conda/...).
On https://matplotlib.org/devdocs/users/installing.html I would add a section "Installing for development" and have there just a link to the contribution docs.
story645 commentedon May 17, 2020
@timhoffm that's fine with me so long as the install from source docs are in one place. I'm fairly certain the top bug for new contributors is that they're using the wrong install instructions.
ETA: like even the mpl install from source docs under user say they're aimed at contributors. I'm not against standalone install from source tarball/release source docs but like that has to be super explicit.
rajpratyush commentedon Mar 16, 2021
@story645 does this issue needs work?
jklymak commentedon Mar 16, 2021
It doesn't seem done to me. We could move any useful info from the FAQ to INSTALL.rst. A quick look at INSTALL.rst, it could probably be trimmed substantially. If we need an "Advanced Installation" page, that might make sense, but I wouldn't call it a FAQ. @rajpratyush if you think you understand the install well enough to try and merge, feel free to give it a shot.
timhoffm commentedon Mar 16, 2021
Part of this will be adressed with #19505. Further work should be based on that.
Btw. as a friendly reminder, it would be great if someone would review #19505.
SauravMaheshkar commentedon Jan 4, 2022
Should this issue be closed after #19725 and #19505 ?
story645 commentedon Jul 14, 2022
Yeah, I think this is consolidated enough by now that the actionable pieces mostly don't have much to do with consolidation.