From aaf3f1c5a17365f2eeb5ea14870f633136d57615 Mon Sep 17 00:00:00 2001 From: Tom Vo Date: Wed, 21 Apr 2021 10:51:01 -0700 Subject: [PATCH] Add xarray resources and VSCode extensions to docs (#41) * Add xarray resources and VSCode extensions to docs * Remove refs to GH Actions publishing docs --- CONTRIBUTING.rst | 32 +++++++++++++++++++------------- docs/index.rst | 2 +- docs/maintainers.rst | 6 ++---- 3 files changed, 22 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 590cb3a6..fcde18e8 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -112,9 +112,11 @@ Recommended VSCode Extensions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * `Python `_ * `Pylance `_ + * `Python Docstring Generator `_ + * `Python Type Hint `_ + * `Better Comments `_ * `Jupyter `_ * `Visual Studio Intellicode `_ - * `Python Docstring Generator `_ Local Development ~~~~~~~~~~~~~~~~~ @@ -150,7 +152,7 @@ Local Development $ conda env create -f conda-env/dev.yml $ conda activate xcdat_dev -5. Install pre-commit (performs quality assurance (QA) checks):: +5. Install pre-commit:: $ pre-commit install pre-commit installed at .git/hooks/pre-commit @@ -159,7 +161,7 @@ Local Development $ git checkout -b -7. `` During or after making changes, perform QA checks using pre-commit:: +7. `` During or after making changes, check for formatting or linting issues using pre-commit:: # Step 9 performs this automatically on staged files in a commit $ pre-commit run --all-files @@ -174,7 +176,8 @@ Local Development 8. Generate code coverage report and check unit tests pass:: - $ pytest + $ make test # Automatically opens HTML report in your browser + $ pytest # Does not automatically open HTML report in your browser ================================= test session starts ================================= platform darwin -- Python 3.8.8, pytest-6.2.2, py-1.10.0, pluggy-0.13.1 @@ -196,7 +199,7 @@ Local Development Coverage HTML written to dir tests_coverage_reports/htmlcov Coverage XML written to file tests_coverage_reports/coverage.xml - - The Coverage HTML file contains a much more detailed coverage report (e.g., exact lines of untested code) + - The Coverage HTML report is much more detailed (e.g., exact lines of tested/untested code) 9. Commit your changes:: @@ -241,9 +244,9 @@ When you open a pull request on GitHub, there is a template available for use. Style Guide ----------- -This project integrates the Black code formatter for code styling. If you want to learn more, please read about it `here `__. +xCDAT integrates the Black code formatter for code styling. If you want to learn more, please read about it `here `__. -It also leverages `Python Type Annotations `_ to help the project scale. +xCDAT also leverages `Python Type Annotations `_ to help the project scale. `mypy `_ performs optional static type checking through pre-commit. Testing @@ -352,24 +355,27 @@ $ pytest tests.test_xcdat FAQs ---- -Why Squash and Rebase Commits? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +What is xarray and how do I extend xarray for xCDAT? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* https://xarray.pydata.org/en/stable/why-xarray.html +* https://xarray.pydata.org/en/stable/internals.html#extending-xarray +What and why for squashing and rebasing commits? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before you merge a support branch back into ``master``, the branch is typically squashed down to a single* buildable commit, and then rebased on top of the main repo's ``master`` branch. \* *In some cases, it might be logical to have multiple squashed commits, as long as each commit passes the CI/CD build* -Why squash and rebase commits? +Why? * Ensures build passes from the commit * Cleans up Git history for easy navigation * Makes collaboration and review process more efficient * Makes handling conflicts from rebasing simple since you only have to deal with conflicted commits -How to Squash and Rebase Commits -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - +How do I squash and rebase commits? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. `` Sync your fork of ``master`` (aka ``origin``) with the root ``master`` (aka ``upstream``) :: git checkout master diff --git a/docs/index.rst b/docs/index.rst index 8a198064..c4d67598 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,7 +2,7 @@ Welcome to xCDAT's documentation! ====================================== .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: Contents: readme diff --git a/docs/maintainers.rst b/docs/maintainers.rst index 094988af..9d1485e4 100644 --- a/docs/maintainers.rst +++ b/docs/maintainers.rst @@ -34,8 +34,7 @@ This project uses `GitHub Actions