Skip to content

made explicit that install link is install docs in readme #23905

New issue

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

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

Merged
merged 1 commit into from
Sep 19, 2022

Conversation

story645
Copy link
Member

@story645 story645 commented Sep 16, 2022

I think it's confusing to tell people read the install docs or install.rst (I totally didn't even parse that they were the same doc at first) and we link to the docs in other sections of the readme.

@tacaswell
Copy link
Member

I am against this change. I think it is important to make the installation instructions be intelligible without an internet connection. Maybe the change that is needed in to make it clear the rst is the source of the rendered page.

@story645
Copy link
Member Author

But if they're installing from source they can find the file in the source, especially since the raw rst is the path to the file. Or they're building the docs locally and then this is the path to the file in the local docs.

@jklymak
Copy link
Member

jklymak commented Sep 16, 2022

I think it is confusing, if for no other reason than installing.rst doesn't exist. But we should definitely point to the source file as well, which shouldn't be that confusing for someone reading a file that is itself in the source.

@story645
Copy link
Member Author

I think it is confusing, if for no other reason than installing.rst doesn't exist.

We have a top level
https://github.com/matplotlib/matplotlib/blob/main/INSTALL.rst which has one line in it which is the path to the full install docs. I think this was either done to satisfy GitHub or cause it's a convention and folks installing from source usually know to look for it.

But yes will compromise and wordsmith to include the path to source.

@story645 story645 changed the title removed link to install src in readme made explict that install link is install docs in readme Sep 16, 2022
@timhoffm
Copy link
Member

I don't really follow the need-source argument. Most users will access README.rst through github because it's the entry page there. They certainly don't need the source information - it's only distracting clutter for them.

Which user group would be affected by removing the source? People who have cloned the repo, then go offline, and then want to install from sources. I attribute these people enough expertise to find INSTALL.rst as well.

But 🤷

@story645 story645 force-pushed the story645-readme branch 2 times, most recently from 04bbedb to 49e50d8 Compare September 16, 2022 21:21
@story645
Copy link
Member Author

story645 commented Sep 16, 2022

They certainly don't need the source information - it's only distracting clutter for them

was gonna shove it in a footnote, but that only works if there are other footnotes on the page

@story645
Copy link
Member Author

made it a little more concise, but put it in a second commit if it's not working.

@timhoffm
Copy link
Member

timhoffm commented Sep 18, 2022

was gonna shove it in a footnote, but that only works if there are other footnotes on the page

Footnote would be a good choice here. The source location is only an addendum. If that does not work, how about

see [link](or it’s corresponding source [path]).

@story645
Copy link
Member Author

story645 commented Sep 18, 2022

So best way to do footnote version is probably by adding a notes section: (as an aside, the research notice should probably not be a subsection of the citation)

image

also squished it down to see [link], which is generated from (path) based on your comments and not gonna bother rebasing again unless I get an approval

off it

Co-authored-by: Thomas A Caswell <tcaswell@gmail.com>
Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
@timhoffm timhoffm merged commit 53feded into matplotlib:main Sep 19, 2022
@timhoffm
Copy link
Member

Let's not overthink this.

@story645 story645 deleted the story645-readme branch September 19, 2022 13:26
@QuLogic QuLogic added this to the v3.7.0 milestone Sep 19, 2022
@QuLogic QuLogic changed the title made explict that install link is install docs in readme made explicit that install link is install docs in readme Jan 25, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants