Improve documentation

[elbeejay]

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

• Closes Functionality or example to handle large requests #68 by improving the quality of the error message associated with the 414 error message to include a pseudo-code example of splitting up a large query into chunks of some size n
• Closes Which data portals does this package pull from? #33 by creating a new page in the documentation with a table of the various data portals dataretrieval pulls data from and their corresponding URLs
• Closes Dataframe not returned from get_water_use() #46 by adding an example of collecting water use data for a single county in Arizona to the doc-string

Additional Examples

• Adds at least 1 if not more examples of function usage to the doc-strings of public functions. These will render below the API documentation for a given function, ex:

• Adds (and dynamically renders) the hydroshare notebooks put together by @horsburgh - notebooks were downloaded from https://www.hydroshare.org/resource/c97c32ecf59b4dff90ef013030c54264/ - they do not directly reference the notebooks but reference the downloaded copies in the 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 run

Doc-strings and linting

• PR includes a bunch of edits to standardize the doc-strings to the numpy format. This includes ensuring headers are Parameters, Other Parameters, Returns, and Examples exclusively in the doc-strings, as well as explicit inclusion of parameter types
• Some linting to conform to standard PEP-standards for spacing in arguments, line lengths, etc.
• Refer to Python objects in the documentation with double backquotes for Python functions and objects outside of the language, e.g., pandas.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
• Execute much of the documented code, anything preceded by .. 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 requires gdal which is not installed on the CI runner at this time

Code Changes

• Adds a private function _alter_kwargs to wqp.py to reduce code repetition by using a function to handle the keyword arguments that are not currently supported by dataretrieval
• Changes the URLs and paths for nadp.py to reflect the current addresses and URL-conventions for the national trends and mercury deposition maps and data

Unit Tests

• Adds tests for the NADP functions with a nadp_test.py file. These tests are marked to xfail as the CI runner doesn't have gdal installed, but they should pass locally when running the test suite
• Adds unit tests for the new _alter_kwargs function within the wqp_test.py file

[thodson-usgs]

Excellent!

[thodson-usgs]

This class isn't idiomatic. Note to self to fix.