8000 Consolidate Install Docs · Issue #17327 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Consolidate Install Docs #17327

New issue

Have a question 8000 about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
6 tasks
story645 opened this issue May 4, 2020 · 12 comments
Closed
6 tasks

Consolidate Install Docs #17327

story645 opened this issue May 4, 2020 · 12 comments
Labels
Documentation Good first issue Open a pull request against these issues if there are no active ones!

Comments

@story645
Copy link
Member
story645 commented May 4, 2020 •
edited
Loading

Installation is documented in at least 4 places:

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:
@story645 story645 changed the title Consoli Consolidate Install Docs May 4, 2020
@r0cketr1kky
Copy link

Hi @story645 , I would like to take this up.

@story645
Copy link
Member Author

go for it!

@r0cketr1kky r0cketr1kky mentioned this issue May 13, 2020
Closed
5 tasks
@r0cketr1kky
Copy link

Do you want me to remove the entire doc/faq folder or only doc/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
Copy link
Member Author

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
Copy link

Sounds like a plan. I'm on it :)

@timhoffm
Copy link
Member

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
Copy link
Member Author
story645 commented May 17, 2020 •
edited
Loading

@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.

@story645 story645 mentioned this issue Jul 14, 2020
Closed
@story645 story645 added the Good first issue Open a pull request against these issues if there are no active ones! label Sep 17, 2020
@Utkarshp1 Utkarshp1 mentioned this issue Dec 20, 2020
Merged
1 task
@timhoffm timhoffm mentioned this issue Jan 2, 2021
Merged
@rajpratyush
Copy link
Contributor

@story645 does this issue needs work?

@jklymak
Copy link
Member
jklymak commented 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
Copy link
Member

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.

@timhoffm timhoffm reopened this Mar 16, 2021
@timhoffm timhoffm mentioned this issue Mar 17, 2021
Merged
@SauravMaheshkar
Copy link

Should this issue be closed after #19725 and #19505 ?

@story645
Copy link
Member Author

Yeah, I think this is consolidated enough by now that the actionable pieces mostly don't have much to do with consolidation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Good first issue Open a pull request against these issues if there are no active ones!
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@story645 @jklymak @timhoffm @r0cketr1kky @rajpratyush @SauravMaheshkar
0