DOC: add button to edit on GitHub

[afeld]

Location of the documentation

https://pandas.pydata.org/docs/

Documentation problem

I'll write it as a user story:

As a pandas user, when I come across a small problem with the documentation (like a typo), I want to be able to suggest a fix with minimal friction.

Currently, contributors need to search the repository to find the corresponding source file.

Suggested fix for documentation

Having an "Edit this page on GitHub" button would help people contribute to documentation quickly. A couple of resources explaining how to do this with Sphinx:

• https://mg.pov.lt/blog/sphinx-edit-on-github.html
• https://gist.github.com/mgedmin/6052926

Could limit to non-API pages to keep things simple. Possible it makes more sense to do this in the theme.

[attack68]

I like this idea, I think it might work well, especially for typos. But it might also have problems...

The API has a more clearly defined structure, it would be easier to approve or decline changes to API docs subject to that. Changes to non-api pages are more subjective, adding in, deleting or editing a sentence here and there might be more difficult to selectively approve based on the number of new participants, and a more dynamic guidebook may be harder to use for regular users. I am assuming the number of editors picks up substantially.

[MarcoGorelli]

Currently, contributors need to search the repository to find the corresponding source file.

TBH I think that having a bit of friction for making a PR is a good thing - I get the impression that PRs done directly from GitHub (usually made from patch-1 branches) tend to be of lower quality

[MarcoGorelli]

Currently, contributors need to search the repository to find the corresponding source file.

TBH I think that having a bit of friction for making a PR is a good thing - I get the impression that PRs done directly from GitHub (usually made from patch-1 branches) tend to be of lower quality

Sorry @afeld , I may have misunderstood what you were suggesting - doesn't the current [source] button on the right already do that?

(as an aside, thanks for all the work you're doing on the docs!)

[afeld]

Seems like the two folks who have commented already are less in favor. Anyone else think it's a good idea? If not, fine to close.

having a bit of friction for making a PR is a good thing

I get what you're saying. Setting up a pandas development is probably an hour minimum — would love a number closer to zero, particularly for working on docs — but that's a whole different problem.

doesn't the current [source] button on the right already do that?

Good point! In that case, talking about the non-API pages.

thanks for all the work you're doing on the docs!

You're welcome! Definitely the largest open source project I've worked on consistently, so getting a lot out of seeing how that works.

[MarcoGorelli]

Setting up a pandas development is probably an hour minimum

True, but the docs do say that you don't need to build pandas locally if you're only interested in building the docs

Good point! In that case, talking about the non-API pages.

OK yes, if non-API pages don't have a button to make the source easily findable, then adding one seems like a good idea

[afeld]

the docs do say that you don't need to build pandas locally if you're only interested in building the docs

Beside the point here, but:

• Not seeing where it says that
• I'm not sure that's true, since Sphinx imports pandas

[MarcoGorelli]

You're right, sorry, it just says

If you’re making documentation changes, you can skip to Contributing to the documentation but if you skip creating the development environment you won’t be able to build the documentation locally before pushing your changes.

So yeah, +1 for adding a button like [source] to non-API pages

[attack68]

Seems like the two folks who have commented already are less in favor. Anyone else think it's a good idea? If not, fine to close.

I said "I like this idea, I think it might work well, especially for typos". sure I cited some potential probs but only potential - helping users to find the source for the non-api is also useful, so I'm more like a +0.5. :P