Thanks to visit codestin.com
Credit goes to github.com

Skip to content

[doc]: add 'validate' section to install docs #26379

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

Closed
story645 opened this issue Jul 24, 2023 · 3 comments · Fixed by #26565
Closed

[doc]: add 'validate' section to install docs #26379

story645 opened this issue Jul 24, 2023 · 3 comments · Fixed by #26565
Labels
Documentation: devdocs files in doc/devel
Milestone

Comments

@story645
Copy link
Member

story645 commented Jul 24, 2023

Documentation Link

https://matplotlib.org/devdocs/devel/development_setup.html

Problem

The install docs don't have instructions on how to check that the install went through correctly. I think, especially for new contributors, it'd be helpful if we offered a drop more guidance.

Suggested improvement

Add a new section to https://github.com/matplotlib/matplotlib/blob/main/doc/devel/development_setup.rst after install in editable mode. This section should:

  1. Have instructions for checking that the version that's installed matches the last commit import matplotib; matplotib.__version__ is the repo import matplotlib; matplotlib.__file__

  2. Link to the running the tests page to verify that the code installed clean: https://github.com/matplotlib/matplotlib/blob/main/doc/devel/testing.rst#L35

  3. Link to the building the docs page to verify that the docs build clean: https://github.com/matplotlib/matplotlib/blob/main/doc/devel/document.rst

Tests and docs should be sentences with links (or a bullet list of table) and not the instructions specifically so that this section acts as an introduction/nudge to those pages and so that we won't have to maintain two sets of instructions.

@story645 story645 added the Documentation: devdocs files in doc/devel label Jul 24, 2023
@timhoffm
Copy link
Member

  1. Have instructions for checking that the version that's installed matches the last commit import matplotib; matplotib.__version__

I'd rather check that matplotlib.__file__ is the checked out git repo.

@rcomer
Copy link
Member

rcomer commented Jul 26, 2023

Should 2 and 3 come with a warning that they are quite expensive to run? Also, how much should a contributor worry if some tests fail? Because some do for me, and I have reason to believe I’m not alone #17096 (comment)

@story645
Copy link
Member Author

Should 2 and 3 come with a warning that they are quite expensive to run?

Definitely, but I think we should encourage em anyways, mostly so that they have a baseline for what is failing before they start making changes. I also think it may be worth adding a note of some sort that says "parts of this build may fail for x/y/z/ reasons. Please reach out on [comms channels] if you're unsure if the failure is due to the changes you've made in your contribution"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation: devdocs files in doc/devel
Projects
None yet
4 participants