-
Notifications
You must be signed in to change notification settings - Fork 36
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
Improve documentation #72
Merged
thodson-usgs
merged 19 commits into
DOI-USGS:master
from
elbeejay:improve-documentation
Dec 28, 2022
Merged
Improve documentation #72
thodson-usgs
merged 19 commits into
DOI-USGS:master
from
elbeejay:improve-documentation
Dec 28, 2022
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
29095a1
to
d8d8dc1
Compare
thodson-usgs
approved these changes
Dec 28, 2022
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Excellent!
@@ -119,6 +136,8 @@ def update_merge(left, right, na_only=False, on=None, **kwargs): | |||
|
|||
|
|||
class Metadata: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This class isn't idiomatic. Note to self to fix.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Labels
bug
Something isn't working
documentation
Question, request, or suggestion for additional documentation
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Improvements to documentation and doc-strings
This looks like a large PR, but it mostly consists of cosmetic changes aimed at improving the rendered documentation and standardizing some of the doc-string and code formatting throughout the package. Given the large size, it might be best to spread the review out over a few days (or weeks) and go through changed files individually due to the number of changes. These changes are summarized below:
Closing Issues
n
dataretrieval
pulls data from and their corresponding URLsAdditional Examples
demos/
subdirectory, it might be possible to pull the latest versions of the notebooks with some fancy CI stuff to download and extract the source notebooks to the proper location every time the documentation workflow is runDoc-strings and linting
Parameters
,Other Parameters
,Returns
, andExamples
exclusively in the doc-strings, as well as explicit inclusion of parameter typespandas.DataFrame
whereas for functions that are within the package, the convention :obj:object
is used, e.g., :obj:dataretrieval.nwis.get_record
as Sphinx is able to automatically link to the relevant API documentation in that case.. doctest::
will be run when the documentation is built, some code is preceded by.. code::
instead because that code is either costly to run (and therefore impractical for the CI job) or requiresgdal
which is not installed on the CI runner at this timeCode Changes
_alter_kwargs
towqp.py
to reduce code repetition by using a function to handle the keyword arguments that are not currently supported bydataretrieval
nadp.py
to reflect the current addresses and URL-conventions for the national trends and mercury deposition maps and dataUnit Tests
nadp_test.py
file. These tests are marked toxfail
as the CI runner doesn't havegdal
installed, but they should pass locally when running the test suite_alter_kwargs
function within thewqp_test.py
file