Skip to content
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.

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

List key development dependencies to install for new contributors #1783

Merged
merged 5 commits into from
Mar 8, 2022
Merged

List key development dependencies to install for new contributors #1783

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0eb529b
List some of the key dev dependencies for developing pygmt locally
weiji14 Mar 4, 2022
26fa507
Merge branch 'main' into doc/clarify-dev-deps
weiji14 Mar 6, 2022
ab8ac74
Reorganize development dependencies in environment.yml into subsections
weiji14 Mar 6, 2022
1fc43ec
Merge branch 'main' into doc/clarify-dev-deps
weiji14 Mar 7, 2022
c2ae7dd
Explicitly use conda env create --file environment.yml
weiji14 Mar 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions doc/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,8 +192,16 @@ It will make your life a lot easier!

The repository includes a conda environment file `environment.yml` with the
specification for all development requirements to build and test the project.
Comment on lines 193 to 194
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The repository includes a conda environment file environment.yml with the
specification for all development requirements to build and test the project.

Actually I feel this sentence is very clear that all dependencies are listed in the environment.yml and people who want to build and test should read the environment.yml file, rather than listing an incompleted list here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A compromise could be to add more sections (via comments) to environment.yml that specify which development dependencies are required for building the docs, running the tests, and/or formatting the code (inspiration from numpy and pandas environment files).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A compromise could be to add more sections (via comments) to environment.yml that specify which development dependencies are required for building the docs, running the tests, and/or formatting the code (inspiration from numpy and pandas environment files).

Yes, that sounds like a good idea actually.

So do we not want to list some of the dev dependencies here in contributing.md? I know it seems redundant, but there are some people who might be from a non-Anaconda/pure-Python-pip sort of world that don't really use that environment.yml file. Listing things like git/dvc/pytest/sphinx here up front will at least give people an idea on what framework PyGMT uses for testing and building documentation.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A compromise could be to add more sections (via comments) to environment.yml that specify which development dependencies are required for building the docs, running the tests, and/or formatting the code (inspiration from numpy and pandas environment files).

Yes, that sounds like a good idea actually.

Yes, I agree.

Listing things like git/dvc/pytest/sphinx here up front will at least give people an idea on what framework PyGMT uses for testing and building documentation.

Fair point.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, environment.yml has been reorganized into subsections (general, linters, testing, documentation) in ab8ac74.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this paragraph also include a short sentence on how to install dependencies with a .yml file? Since it's different than the typical pip install -r requirements.txt, it would cut down on confusion of how to use environment.yml to install dependencies.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. There's actually a conda env create instruction just a few sentences below. I've just added a commit (c2ae7dd) to make it more explicit (conda env create --file environment.yml).

In particular, these are some of the key development dependencies you will need
to install to build the documentation and run the unit tests locally:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Building the documentation needs more packages (like sphinx) than listed here.


- git (for cloning the repo and tracking changes in code)
- dvc (for downloading baseline images used in tests)
- pytest-mpl (for checking that generated plots match the baseline)
- sphinx-gallery (for building the gallery example page)

See the [`environment.yml`](https://github.com/GenericMappingTools/pygmt/blob/main/environment.yml)
file for the list of dependencies and the environment name (`pygmt`).
file for the full list of dependencies and the environment name (`pygmt`).
Once you have forked and cloned the repository to your local machine, you can
use this file to create an isolated environment on which you can work.
Run the following on the base of the repository to create a new conda
Expand All @@ -210,7 +218,6 @@ Before building and testing the project, you have to activate the environment
conda activate pygmt
```


We have a [`Makefile`](https://github.com/GenericMappingTools/pygmt/blob/main/Makefile)
that provides commands for installing, running the tests and coverage analysis,
running linters, etc. If you don't want to use `make`, open the `Makefile` and
Expand Down
17 changes: 10 additions & 7 deletions environment.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,25 @@ dependencies:
- packaging
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line 7: can we remove pip from the list?

Copy link
Member Author

@weiji14 weiji14 Mar 6, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could, but then people might get a warning that says: "Warning : you have pip-installed dependencies in your environment file, but you do not list pip itself as one of your conda dependencies...". See https://stackoverflow.com/questions/58544099/warning-after-i-run-the-command-conda-env-create-f-environment-yml.

Edit: Oh wait, actually that warning won't show up since we don't list pip dependencies, but I think listing it explicitly doesn't really hurt?

# Optional dependencies
- geopandas
# Development dependencies
# Development dependencies (general)
- dvc
- ipython
- jupyter
- make
# Dev dependencies (style checks)
- black
- blackdoc
- docformatter
- dvc
- flake8
- ipython
- isort>=5
- jupyter
- make
- matplotlib
- myst-parser
- pylint
# Dev dependencies (unit testing)
- matplotlib
- pytest-cov
- pytest-mpl
- pytest>=6.0
# Dev dependencies (building documentation)
- myst-parser
- sphinx
- sphinx-copybutton
- sphinx-gallery
Expand Down