issues: 1532853152

This data as json

id node_id number title user state locked assignee milestone comments created_at updated_at closed_at author_association active_lock_reason draft pull_request body reactions performed_via_github_app state_reason repo type
1532853152 I_kwDOAMm_X85bXXug 7439 Add clarifying language to contributor's guide 26591824 closed 0     3 2023-01-13T20:11:57Z 2023-03-13T17:51:26Z 2023-03-13T17:51:26Z CONTRIBUTOR      

What is your issue?

I am going through the contributor's guide for xarray, and I have a few suggested updates to make the instructions clearer to relatively new contributors like me!

General questions

  • If making updates to docstrings, I am unclear if I should use the virtual env xarray-tests or xarray-docs. I assumed I should use xarray-docs since I am only updating docstrings which are fed into the documentation. But this isn't entirely clear, since the file I updated is not in the \docs folder, but is at \xarray\backends\api.rst.
  • If only updating docs or docstrings, should I still run pytest locally before pushing? Or do those tests only apply to code updates? Either way, this should be made clear in the contributing guide.

Suggestion updates

  • Under Code Formatting:
  • Contributors are recommended to use pre-commit via pre-commit install, but when I tried this I found that pre-commit was not installed in the virtual env xarray-docs. It does appear to be installed in virtual env xarray-tests (yml file). Should I run pre-commit when updating docs? If so, we should add pre-commit to virtual env xarray-docs (yml file).
  • Under Building the Documentation:
  • Add a sentence to make it clear that users can preview the html files from their updated documentation in their local browsers to verify it looks as expected. (This is a minor suggestion, but we might as well be as explicit as possible, especially since docs might more likely be updated by newer contributors.)
  • Suggested wording update: "Then you can find the HTML output in the folder xarray/doc/_build/html/. You can preview the html files in your local browser to verify that you see expected behavior based on your changes."
 
{
    "url": "https://api.github.com/repos/pydata/xarray/issues/7439/reactions",
    "total_count": 2,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 2,
    "rocket": 0,
    "eyes": 0
}
   completed 13221727 issue

Links from other tables