Merge pull request #2 from mgm702/develop

V1.0.0 release

Author: mgm702

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.2'
+        bundler-cache: true
+
+    - name: Install dependencies
+      run: bundle install
+
+    - name: Generate YARD documentation
+      run: bundle exec yard doc
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v4
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: './doc'
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

README.md

@@ -1,39 +1,256 @@
-# Usgs::Ruby
+# **usgs-ruby**
 
-TODO: Delete this and the text below, and describe your gem
+[![Build Status](https://github.com/YOUR_USERNAME/usgs-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_USERNAME/usgs-ruby/actions)
+[![Gem Version](https://badge.fury.io/rb/usgs-ruby.svg)](https://badge.fury.io/rb/usgs-ruby)
+[![MIT license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/usgs/ruby`. To experiment with that code, run `bin/console` for an interactive prompt.
+[**« USGS »**](https://www.usgs.gov/)
 
-## Installation
+[**USGS Water Services**](https://waterservices.usgs.gov/)
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+The goal of [**`usgs-ruby`**](https://rubygems.org/gems/usgs-ruby) is to provide functions that help Ruby users to navigate, explore, and make requests to the USGS Water Services API. 
 
-Install the gem and add to the application's Gemfile by executing:
+The United States Geological Survey (USGS) Water Services provides access to water resources data collected at approximately 1.9 million sites across the United States. This includes real-time and historical data for streamflow, groundwater levels, water quality, and more.
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+Thank you to the USGS for providing an accessible and well-documented API!
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+---
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+## **Installation**
 
-## Usage
+Add this line to your application's Gemfile:
 
-TODO: Write usage instructions here
+```ruby
+gem 'usgs-ruby'
+```
 
-## Development
+and then execute:
+
+```bash
+bundle install
+```
+
+or install it yourself as:
+
+```bash
+gem install usgs-ruby
+```
+
+## **Getting Started**
+
+Using the gem is simple. Create a client and start making requests:
+
+```ruby
+require 'usgs'
+
+# Create a client
+client = Usgs.client
+
+# Get site information
+sites = client.get_sites(state_cd: "CO", parameter_cd: :discharge)
+
+# Get daily values (last 24 hours by default)
+readings = client.get_dv(sites: "06754000", parameter_cd: :discharge)
+
+# Get instantaneous values
+iv_readings = client.get_iv(sites: "06754000", parameter_cd: :discharge)
+
+# Get statistics
+stats = client.get_stats(sites: "06754000", report_type: :daily)
+```
+
+## **Available Endpoints**
+
+The `usgs-ruby` gem provides access to all major USGS Water Services endpoints through an intuitive interface. For detailed documentation on each endpoint and its methods, please visit our [documentation site](https://YOUR_USERNAME.github.io/usgs-ruby).
+
+### Key Modules:
+
+* **Daily Values (DV)** - Access daily streamflow, groundwater, and water quality data
+  ```ruby
+  client.get_dv(sites: "06754000", parameter_cd: :discharge, 
+                start_date: "2023-01-01", end_date: "2023-12-31")
+  ```
+
+* **Instantaneous Values (IV)** - Get real-time water data (15-minute intervals)
+  ```ruby
+  client.get_iv(sites: "06754000", parameter_cd: :discharge)
+  ```
+
+* **Site Information** - Search and retrieve monitoring location metadata
+  ```ruby
+  client.get_sites(state_cd: "CO", site_type: "ST", parameter_cd: :discharge)
+  ```
+
+* **Statistics** - Access statistical summaries (daily, monthly, annual)
+  ```ruby
+  client.get_stats(sites: "06754000", report_type: :annual, 
+                   stat_year_type: "water")
+  ```
+
+### Supported Parameter Codes:
+
+The gem includes convenient symbols for common parameters:
+
+- `:discharge` - Streamflow (cubic feet per second)
+- `:gage_height` - Gage height (feet)
+- `:temperature` - Water temperature (°C)
+- `:precipitation` - Precipitation (inches)
+- `:do` - Dissolved oxygen (mg/L)
+- `:conductivity` - Specific conductance (µS/cm)
+- `:ph` - pH
+
+You can also use USGS parameter codes directly (e.g., `"00060"` for discharge).
+
+## **Examples**
+
+### Finding Sites
+
+```ruby
+# Search by state
+sites = client.get_sites(state_cd: "CO")
+
+# Search by bounding box (west, south, east, north)
+sites = client.get_sites(bBox: "-105.5,39.5,-105.0,40.0")
+
+# Search by site name
+sites = client.get_sites(site_name: "Boulder Creek")
+
+# Filter by site type and parameter
+sites = client.get_sites(state_cd: "CO", site_type: "ST", 
+                         parameter_cd: :discharge)
+```
+
+### Retrieving Data
+
+```ruby
+# Get recent daily values
+readings = client.get_dv(sites: "06754000", parameter_cd: :discharge)
+
+# Get historical daily values
+readings = client.get_dv(
+  sites: "06754000",
+  parameter_cd: :discharge,
+  start_date: Date.parse("2020-01-01"),
+  end_date: Date.parse("2023-12-31")
+)
+
+# Get multiple parameters
+readings = client.get_dv(
+  sites: "06754000",
+  parameter_cd: [:discharge, :gage_height]
+)
+
+# Get data from multiple sites
+readings = client.get_dv(
+  sites: ["06754000", "06752000"],
+  parameter_cd: :discharge
+)
+```
+
+### Working with Statistics
+
+```ruby
+# Daily statistics
+stats = client.get_stats(sites: "06754000", report_type: :daily)
+
+# Monthly statistics
+stats = client.get_stats(sites: "06754000", report_type: :monthly)
+
+# Annual statistics (water year)
+stats = client.get_stats(
+  sites: "06754000", 
+  report_type: :annual,
+  stat_year_type: "water"
+)
+```
+
+## **Configuration**
+
+You can configure the client with custom options:
+
+```ruby
+Usgs.configure do |config|
+  config.user_agent = "MyApp/1.0 (contact@example.com)"
+end
+
+client = Usgs.client
+```
+
+## **Development**
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. 
+
+### Running Tests
+
+```bash
+bundle exec rake test
+```
+
+### Generating Documentation
+
+```bash
+bundle exec yard doc
+open doc/index.html
+```
+
+### Running RuboCop
+
+```bash
+bundle exec rubocop
+```
+
+## **Testing**
+
+This gem uses VCR for recording HTTP interactions during testing. When writing tests:
+
+1. Tests will record real API responses on first run
+2. Subsequent runs use cached responses (cassettes)
+3. Cassettes are stored in `test/fixtures/vcr_cassettes/`
+
+## **Contributing**
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-new-feature`)
+3. Write tests for your changes
+4. Make your changes and ensure tests pass (`rake test`)
+5. Run RuboCop and fix any violations (`rubocop`)
+6. Commit your changes with clear, descriptive messages
+7. Push to your branch (`git push origin feature/my-new-feature`)
+8. Create a Pull Request
+
+Please make sure that your commit messages are clear and understandable.
+
+## **Documentation**
+
+Full API documentation is available at [https://YOUR_USERNAME.github.io/usgs-ruby](https://YOUR_USERNAME.github.io/usgs-ruby)
+
+## **Resources**
+
+- [USGS Water Services](https://waterservices.usgs.gov/)
+- [USGS Water Services REST API Documentation](https://waterservices.usgs.gov/rest/Site-Service.html)
+- [USGS Parameter Codes](https://help.waterdata.usgs.gov/parameter_cd?group_cd=%)
+
+## **License**
+
+The usgs-ruby gem is licensed under the MIT license. See [LICENSE](LICENSE) for details.
+
+## **Acknowledgments**
 
-## Contributing
+- Thanks to the USGS for maintaining an excellent public API
+- Inspired by similar projects in other languages
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/mgm702/usgs-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/mgm702/usgs-ruby/blob/main/CODE_OF_CONDUCT.md).
+## **Support**
 
-## License
+If you encounter any issues or have questions:
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+1. Check the [documentation](https://YOUR_USERNAME.github.io/usgs-ruby)
+2. Search existing [GitHub Issues](https://github.com/YOUR_USERNAME/usgs-ruby/issues)
+3. Open a new issue with a clear description and example code
 
-## Code of Conduct
+---
 
-Everyone interacting in the Usgs::Ruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mgm702/usgs-ruby/blob/main/CODE_OF_CONDUCT.md).
+**Like the gem?** Star the repository on [GitHub](https://github.com/YOUR_USERNAME/usgs-ruby)!

Rakefile

@@ -2,15 +2,23 @@
 
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "rubocop/rake_task"
+require "yard"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList["test/**/test_*.rb"]
 end
 
-require "rubocop/rake_task"
-
 RuboCop::RakeTask.new
 
 task default: %i[test rubocop]
+
+YARD::Rake::YardocTask.new do |t|
+  t.options = ["--output-dir", "docs"]
+end
+
+task :publish_docs do
+  sh "git subtree push --prefix docs origin gh-pages"
+end