Merge pull request #74 from csdms/mcflugen/convert-to-myst

Update the docs and convert to myst

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/psf/black
-  rev: 23.1.0
+  rev: 23.7.0
   hooks:
   - id: black
     name: black
@@ -23,7 +23,7 @@ repos:
     additional_dependencies: [".[jupyter]"]
 
 - repo: https://github.com/pycqa/flake8
-  rev: 6.0.0
+  rev: 6.1.0
   hooks:
   - id: flake8
     additional_dependencies:
@@ -42,7 +42,7 @@ repos:
     language: python
 
 - repo: https://github.com/asottile/pyupgrade
-  rev: v3.3.1
+  rev: v3.10.1
   hooks:
   - id: pyupgrade
     args: [--py39-plus]
@@ -68,7 +68,7 @@ repos:
     - id: trailing-whitespace
 
 - repo: https://github.com/regebro/pyroma
-  rev: "4.1"
+  rev: "4.2"
   hooks:
   - id: pyroma
     args: ["-d", "--min=10", "."]

.readthedocs.yaml

@@ -10,13 +10,8 @@ sphinx:
   configuration: docs/source/conf.py
   fail_on_warning: false
 
-formats:
-  - htmlzip
-
 python:
   install:
     - requirements: docs/requirements.txt
-
     - method: pip
       path: .
-  system_packages: false

AUTHORS.md

@@ -0,0 +1,9 @@
+# Credits
+
+## Development Lead
+
+- Eric Hutton (@mcflugen)
+
+## Contributors
+
+None yet. Why not be the first?

CHANGES.md

@@ -0,0 +1,83 @@
+# Release Notes
+
+
+```{towncrier-draft-entries} Not yet released
+```
+
+<!-- towncrier-draft-entries:: Not yet released -->
+
+<!-- towncrier release notes start -->
+
+## 0.2.0 (2022-06-17)
+
+### New Features
+
+- Added a new subcommand, *plot*, to the *ww3* command-line program.
+  `ww3 plot` with download (if the data files are not already cached) and
+  create a plot of the requested data. ([#13](https://github.com/csdms/bmi-wavewatch3/issues/13))
+
+### Bug Fixes
+
+- Fixed a bug in the reporting of an error caused by an invalide datatime
+  string. ([#13](https://github.com/csdms/bmi-wavewatch3/issues/13))
+
+## 0.1.1 (2022-06-10)
+
+### Other Changes and Additions
+
+- Set up GitHub Action to create a source distribution and push it to
+  *TestPyPI*. This action is only run if the version tag is a prerelease version
+  (i.e. the version string ends with `[ab][0-9]+`). ([#10](https://github.com/csdms/bmi-wavewatch3/issues/10))
+- Set up GitHub Action to create a source distribution and push it to
+  *PyPI*. This action is only run if the version tag is a release version
+  (i.e. the version string doesn't end with `[ab][0-9]+`). ([#11](https://github.com/csdms/bmi-wavewatch3/issues/11))
+
+## 0.1.1b1 (2022-06-09)
+
+### New Features
+
+- Added `ww3` command line interface to download WaveWatch III data by date,
+  region and quantity (significant wave height, wind speed, etc.). ([#1](https://github.com/csdms/bmi-wavewatch3/issues/1))
+- Added `WaveWatch3` class, which is the main access point for users of this package.
+  This class downloads WaveWatch III data files (if not already cached) and provides a
+  view of the data as an xarray Dataset. Users can then advance through the data
+  month-by-month, downloading additional data as necessary. ([#3](https://github.com/csdms/bmi-wavewatch3/issues/3))
+- Added the `ww3 clean` subcommand that removes cached data files. ([#4](https://github.com/csdms/bmi-wavewatch3/issues/4))
+- Added `BMIWaveWatch3` class to provide a Basic Model Interface for the
+  *wavewatch3* package. ([#5](https://github.com/csdms/bmi-wavewatch3/issues/5))
+- Added additional WaveWatch III data sources from which users can fraw data
+  from. ([#6](https://github.com/csdms/bmi-wavewatch3/issues/6))
+- Added `fetch` method to WaveWatch3 to mimic the command line program
+  `ww3 fetch`. ([#7](https://github.com/csdms/bmi-wavewatch3/issues/7))
+- Added additional data sources from which to retreive data from. Available
+  data sources now include: Phase 1, Phase 2, Multigrid, Multigrid-extended,
+  and Multigrid-thredds. ([#7](https://github.com/csdms/bmi-wavewatch3/issues/7))
+- Added `ww3 info` command to print information (e.g. available grids, quantities,
+  etc.) about data sources. ([#7](https://github.com/csdms/bmi-wavewatch3/issues/7))
+- Added a `step` property to `WaveWatch3` to track the current time slice
+  of the data cube. This property is also settable so that a user can use it to
+  advance throught the data (additional data are downloaded in the background as
+  needed). ([#8](https://github.com/csdms/bmi-wavewatch3/issues/8))
+- Dates can now be specified as iso-formatted date/time strings. For example,
+  "1944-06-06T06:30". ([#8](https://github.com/csdms/bmi-wavewatch3/issues/8))
+- Rename package to `bmi_wavewatch3`. This follows the convention used by other
+  CSDMS data components. ([#9](https://github.com/csdms/bmi-wavewatch3/issues/9))
+
+### Documentation Enhancements
+
+- Added package description, installation, usage, and an example to the
+  documentation. ([#8](https://github.com/csdms/bmi-wavewatch3/issues/8))
+
+### Other Changes and Additions
+
+- Set up continuous integration using GitHub actions. This includes tests to
+  ensure that the code is styled according to *black*, is free of lint, and
+  passes all unit tests. ([#2](https://github.com/csdms/bmi-wavewatch3/issues/2))
+- Added more unit tests, particularly for data sources. ([#7](https://github.com/csdms/bmi-wavewatch3/issues/7))
+- Added a GitHub action to build the sphinx-based documentation as part of the
+  continuous integration. ([#8](https://github.com/csdms/bmi-wavewatch3/issues/8))
+- Better error reporting for the command line interface for HTTP errors when
+  retreiving data as well as input validation. ([#8](https://github.com/csdms/bmi-wavewatch3/issues/8))
+- Set up GitHub Action to create a source distribution and push it to
+  *TestPyPI*. This action is only run if the version tag is a prerelease version
+  (i.e. the version string ends with `[ab][0-9]+`). ([#10](https://github.com/csdms/bmi-wavewatch3/issues/10))

LICENSE.rst → LICENSE.md

@@ -1,5 +1,4 @@
-The MIT License (MIT)
-=====================
+# The MIT License (MIT)
 
 Copyright (c) `2022` `Community Surface Dynamics Modeling System`
 

MANIFEST.in

@@ -1,4 +1,4 @@
-include CHANGES.rst
+include CHANGES.md
 include CITATION.cff
 include .pre-commit-config.yaml
 include .python-version

README.md

@@ -0,0 +1,76 @@
+[![Python interface to WAVEWATCH III data][logo]][github-link]
+
+
+# WAVEWATCH III data in Python
+
+[![Documentation status][rtd-badge]][rtd-link]
+[![Code-style: Black][black-badge]][black-link]
+[![Testing status][testing-badge]][testing-link]
+![Flake8][flake8-badge]
+
+
+## About
+
+
+<!-- start-abstract -->
+
+The *bmi_wavewatch3* Python package provides both a command line interface and
+a programming interface for downloading and working with [WAVEWATCH III] data.
+
+*bmi_wavewatch3* provides access to the following raster data sources,
+
+- 30 year wave hindcast [Phase 1]
+- 30 year wave hindcast [Phase 2]
+- Production hindcast [Singlegrid]
+- Production hindcast [Multigrid]
+
+All data sources provide both global and regional grids.
+
+[phase 1]: https://polar.ncep.noaa.gov/waves/hindcasts/nopp-phase1.php
+[phase 2]: https://polar.ncep.noaa.gov/waves/hindcasts/nopp-phase2.php
+[singlegrid]: https://polar.ncep.noaa.gov/waves/hindcasts/prod-nww3.php
+[multigrid]: https://polar.ncep.noaa.gov/waves/hindcasts/prod-multi_1.php
+
+<!-- end-abstract -->
+
+[**See the bmi-wavewatch3 documentation for more information**](https://bmi-wavewatch3.readthedocs.io/en/latest/).
+
+## Installation
+
+To install the latest release of *bmi-wavewatch3* using *pip*, simply run the following
+in your terminal of choice:
+
+```bash
+pip install bmi-wavewatch3
+```
+
+For a full description of how to install *bmi-wavewatch3*, including using *mamba*/*conda*,
+please see the documentation for our [installation instructions].
+
+## Source code
+
+If you would like to modify or contribute code to *bmi-wavewatch3* or use the very
+latest development version, please see the documentation that describes how to
+[install bmi-wavewatch3 from source].
+
+
+[install bmi-wavewatch3 from source]: https://bmi-wavewatch3.readthedocs.io/en/master/install/developer_install.html
+[installation instructions]: https://bmi-wavewatch3.readthedocs.io/en/master/installation.html
+[multigrid data]: https://polar.ncep.noaa.gov/waves/hindcasts/multi_1/
+[singlegrid data]: https://polar.ncep.noaa.gov/waves/hindcasts/nww3/
+[wavewatch iii]: https://polar.ncep.noaa.gov/waves
+[wavewatch iii description]: https://polar.ncep.noaa.gov/waves/wavewatch/
+[wavewatch iii hindcasts]: http://polar.ncep.noaa.gov/waves/hindcasts/
+[wavewatch iii thredds]: https://www.ncei.noaa.gov/thredds-ocean/catalog/ncep/nww3/catalog.html
+
+
+[black-badge]: https://github.com/csdms/bmi-wavewatch3/workflows/Black/badge.svg
+[black-link]: https://github.com/ambv/black
+[flake8-badge]: https://github.com/csdms/bmi-wavewatch3/workflows/Flake8/badge.svg
+[github-link]: https://github.com/csdms/bmi-wavewatch3
+[logo]: https://github.com/csdms/bmi-wavewatch3/raw/main/docs/source/_static/bmi-wavewatch3-logo-light.svg
+[rtd-badge]: https://readthedocs.org/projects/bmi-wavewatch3/badge/?version=latest
+[rtd-link]: https://bmi-wavewatch3.readthedocs.io/en/latest/?badge=latest
+[testing-badge]: https://github.com/csdms/bmi-wavewatch3/actions/workflows/test.yml/badge.svg
+[testing-link]: https://github.com/csdms/bmi-wavewatch3/actions/workflows/test.yml
+[ww3-global-image]: https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/ww3_global_swh-light.png