docs: Python ports of the new USGS Water Data API vignettes

[thodson-usgs]

Summary

Ports the five new USGS Water Data API vignettes from the R
dataRetrieval package to the
Python dataretrieval.waterdata module as executable demo notebooks, and wires
them into the Sphinx docs under a new "USGS Water Data API vignettes" section.

New notebook (demos/)	R source vignette	Key functions
USGS_WaterData_Introduction_Examples	read_waterdata_functions.Rmd	the whole get_* family + CQL filters
USGS_WaterData_DiscreteSamples_Examples	samples_data.Rmd	get_samples, get_samples_summary, get_codes
USGS_WaterData_DailyStatistics_Examples	daily_data_statistics.Rmd	get_stats_por, get_stats_date_range, get_daily
USGS_WaterData_ContinuousData_Examples	continuous_pr.Rmd	get_continuous, get_combined_metadata
USGS_WaterData_ReferenceLists_Examples	Reference_Lists.Rmd	get_reference_table

Notes

• Each notebook was executed end-to-end against the live USGS Water Data API
  during development (0 errors). Outputs are cleared per the repo convention
  — the sphinx-docs workflow re-executes notebooks at build time
  (nbsphinx_execute = auto).
• Notebook filenames follow the existing USGS_WaterData_<Topic>_Examples
  convention; code cells are formatted with black-jupyter (23.3.0, matching
  .pre-commit-config.yaml).
• The full Sphinx build (make html) succeeds and renders all five pages with
  their plots; no new build warnings.

R → Python adaptations worth a look

• CQL queries use filter= / filter_lang="cql-text"; the library deliberately
  rejects unquoted numeric comparisons (the API types everything as strings), so
  the drainage-area example uses a pandas-side numeric reduction instead.
• read_waterdata_metadata → get_reference_table; read_waterdata_parameter_codes
  → get_reference_table(collection="parameter-codes"); check_OGC_requests has no
  Python equivalent, so the properties= argument is demonstrated directly.
• get_stats_* use computation_type= (vs R computation=) and have no
  normal_type / interval_type args yet, so those filters are applied in pandas;
  their string value column is coerced to numeric for plotting/aggregation.

🤖 Generated with Claude Code