From a24a57e5519d5832a8ef51821bffd6689e1e9ff3 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 7 Sep 2023 18:09:28 -0600 Subject: [PATCH 01/15] convert rst files to myst --- AUTHORS.md | 9 + AUTHORS.rst | 12 - CHANGES.md | 81 +++++++ CHANGES.rst | 94 -------- LICENSE.rst => LICENSE.md | 3 +- README.md | 215 +++++++++++++++++ README.rst | 221 ------------------ docs/source/authors.md | 2 + docs/source/authors.rst | 1 - docs/source/changes.md | 2 + docs/source/changes.rst | 1 - docs/source/index.md | 57 +++++ docs/source/index.rst | 51 ---- docs/source/install/basic_install.md | 53 +++++ docs/source/install/basic_install.rst | 48 ---- .../{environments.rst => environments.md} | 16 +- docs/source/install/index.md | 12 + docs/source/install/index.rst | 10 - .../{source_install.rst => source_install.md} | 44 ++-- docs/source/license.md | 2 + docs/source/license.rst | 1 - docs/source/plotting.md | 6 + docs/source/plotting.rst | 6 - docs/source/usage.md | 6 + docs/source/usage.rst | 6 - 25 files changed, 479 insertions(+), 480 deletions(-) create mode 100644 AUTHORS.md delete mode 100644 AUTHORS.rst create mode 100644 CHANGES.md delete mode 100644 CHANGES.rst rename LICENSE.rst => LICENSE.md (96%) create mode 100644 README.md delete mode 100644 README.rst create mode 100644 docs/source/authors.md delete mode 100644 docs/source/authors.rst create mode 100644 docs/source/changes.md delete mode 100644 docs/source/changes.rst create mode 100644 docs/source/index.md delete mode 100644 docs/source/index.rst create mode 100644 docs/source/install/basic_install.md delete mode 100644 docs/source/install/basic_install.rst rename docs/source/install/{environments.rst => environments.md} (82%) create mode 100644 docs/source/install/index.md delete mode 100644 docs/source/install/index.rst rename docs/source/install/{source_install.rst => source_install.md} (55%) create mode 100644 docs/source/license.md delete mode 100644 docs/source/license.rst create mode 100644 docs/source/plotting.md delete mode 100644 docs/source/plotting.rst create mode 100644 docs/source/usage.md delete mode 100644 docs/source/usage.rst diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..4f77d0c --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,9 @@ +# Credits + +## Development Lead + +- Eric Hutton (@mcflugen) + +## Contributors + +None yet. Why not be the first? diff --git a/AUTHORS.rst b/AUTHORS.rst deleted file mode 100644 index 60f3cc3..0000000 --- a/AUTHORS.rst +++ /dev/null @@ -1,12 +0,0 @@ -Credits -======= - -Development Lead ----------------- - -* Eric Hutton (@mcflugen) - -Contributors ------------- - -None yet. Why not be the first? diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..d96a253 --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,81 @@ +# Release Notes + +```{eval-rst} +.. 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)) diff --git a/CHANGES.rst b/CHANGES.rst deleted file mode 100644 index 831e3d9..0000000 --- a/CHANGES.rst +++ /dev/null @@ -1,94 +0,0 @@ -Release Notes -============= - -.. 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 `_) - - -Bug Fixes -````````` - -- Fixed a bug in the reporting of an error caused by an invalide datatime - string. (`#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 `_) -- 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 `_) - - -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 `_) -- 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 `_) -- Added the ``ww3 clean`` subcommand that removes cached data files. (`#4 `_) -- Added ``BMIWaveWatch3`` class to provide a Basic Model Interface for the - *wavewatch3* package. (`#5 `_) -- Added additional WaveWatch III data sources from which users can fraw data - from. (`#6 `_) -- Added ``fetch`` method to WaveWatch3 to mimic the command line program - ``ww3 fetch``. (`#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 `_) -- Added ``ww3 info`` command to print information (e.g. available grids, quantities, - etc.) about data sources. (`#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 `_) -- Dates can now be specified as iso-formatted date/time strings. For example, - "1944-06-06T06:30". (`#8 `_) -- Rename package to ``bmi_wavewatch3``. This follows the convention used by other - CSDMS data components. (`#9 `_) - - -Documentation Enhancements -`````````````````````````` - -- Added package description, installation, usage, and an example to the - documentation. (`#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 `_) -- Added more unit tests, particularly for data sources. (`#7 `_) -- Added a GitHub action to build the sphinx-based documentation as part of the - continuous integration. (`#8 `_) -- Better error reporting for the command line interface for HTTP errors when - retreiving data as well as input validation. (`#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 `_) diff --git a/LICENSE.rst b/LICENSE.md similarity index 96% rename from LICENSE.rst rename to LICENSE.md index 7496260..318e7d1 100644 --- a/LICENSE.rst +++ b/LICENSE.md @@ -1,5 +1,4 @@ -The MIT License (MIT) -===================== +# The MIT License (MIT) Copyright (c) `2022` `Community Surface Dynamics Modeling System` diff --git a/README.md b/README.md new file mode 100644 index 0000000..cf10a2d --- /dev/null +++ b/README.md @@ -0,0 +1,215 @@ +```{image} https://github.com/csdms/bmi-wavewatch3/raw/main/docs/source/_static/bmi-wavewatch3-logo-light.svg +:alt: Python interface to WAVEWATCH III data +:target: https://github.com/csdms/bmi-wavewatch3 +``` + +# WAVEWATCH III data in Python + +```{image} https://github.com/csdms/bmi-wavewatch3/actions/workflows/test.yml/badge.svg +:alt: Test status +:target: https://github.com/csdms/bmi-wavewatch3/actions/workflows/test.yml +``` + +```{image} https://github.com/csdms/bmi-wavewatch3/workflows/Flake8/badge.svg +``` + +```{image} https://github.com/csdms/bmi-wavewatch3/workflows/Black/badge.svg +``` + +## 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 + +## 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]. + +## Usage + +% start-usage + +To get started, you can download *WAVEWATCH III* data by date with the *ww3* command +(use `ww3 --help` to print a brief message), + +```bash +ww3 fetch "2010-05-22" +``` + +You can also do this through Python, + +```pycon +>>> from bmi_wavewatch3 import WaveWatch3 +>>> WaveWatch3.fetch("2010-05-22") +``` + +The *bmi_wavewatch3* package provides the `WaveWatch3` class for downloading data and +presenting it as an *xarray* *Dataset*. + +```pycon +>>> from bmi_wavewatch3 import WaveWatch3 +>>> ww3 = WaveWatch3("2010-05-22") +>>> ww3.data + +... +``` + +Use the `inc` method to advance in time month-by-month, + +```pycon +>>> ww3.date +'2010-05-22' +>>> ww3.inc() +'2010-06-22' +>>> ww3.data.time + +array('2010-06-01T00:00:00.000000000', dtype='datetime64[ns]') +... +``` + +This will download new datasets as necessary and load the new data into the `data` +attribute. + +:::{note} +If the new data are not cached on you computer, you will notice a delay while the new +data are download. If the `lazy` flag is set, the download will only occur once you +try to access the data (i.e. `ww3.data`), otherwise the data are downloaded +as soon as the date is set. +::: + +## Example + +### Plot data from the command line + +Running the following from the command line will plot the variable +*significant wave height* from the WAVEWATCH III *at_4m* grid. Note that the time of +day (in this case, 15:00) is separated from the date with a `T` (i.e. times can be +given as `YYYY-MM-DDTHH`) + +```bash +ww3 plot --grid=at_4m --data-var=swh "2010-09-15T15" +``` + +```{image} https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/hurricane_julia-light.png +:align: center +:alt: Hurricane Julia +:class: only-light +:width: 100% +``` + +```{image} https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/hurricane_julia-dark.png +:align: center +:alt: Hurricane Julia +:class: only-dark +:width: 100% +``` + +% end-usage + +### Plot data from Python + +% start-plotting + +This example is similar to the previous but uses the *bmi_wavewatch3* Python interface. + +```pycon +>>> from bmi_wavewatch3 import WaveWatch3 +>>> ww3 = WaveWatch3("2009-11-08") +``` + +The data can be accessed as an *xarray* *Dataset* through the `data` attribute. + +```pycon +>>> ww3.data + +Dimensions: (step: 241, latitude: 311, longitude: 720) +Coordinates: + time datetime64[ns] 2009-11-01 + * step (step) timedelta64[ns] 0 days 00:00:00 ... 30 days 00:00:00 + surface float64 1.0 + * latitude (latitude) float64 77.5 77.0 76.5 76.0 ... -76.5 -77.0 -77.5 + * longitude (longitude) float64 0.0 0.5 1.0 1.5 ... 358.0 358.5 359.0 359.5 + valid_time (step) datetime64[ns] dask.array +Data variables: + dirpw (step, latitude, longitude) float32 dask.array + perpw (step, latitude, longitude) float32 dask.array + swh (step, latitude, longitude) float32 dask.array + u (step, latitude, longitude) float32 dask.array + v (step, latitude, longitude) float32 dask.array +Attributes: + GRIB_edition: 2 + GRIB_centre: kwbc + GRIB_centreDescription: US National Weather Service - NCEP + GRIB_subCentre: 0 + Conventions: CF-1.7 + institution: US National Weather Service - NCEP + history: 2022-06-08T16:08 GRIB to CDM+CF via cfgrib-0.9.1... +``` + +The `step` attribute points to the current time slice into the data (i.e number of +three hour increments since the start of the month), + +```pycon +>>> ww3.step +56 +>>> ww3.data.swh[ww3.step, :, :].plot() +``` + +```{image} https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/ww3_global_swh-light.png +:align: center +:alt: Significant wave height +:class: only-light +:target: https://bmi-wavewatch3.readthedocs.org/ +:width: 100% +``` + +```{image} https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/ww3_global_swh-dark.png +:align: center +:alt: Significant wave height +:class: only-dark +:target: https://bmi-wavewatch3.readthedocs.org/ +:width: 100% +``` + +% end-plotting + +[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 diff --git a/README.rst b/README.rst deleted file mode 100644 index dc35699..0000000 --- a/README.rst +++ /dev/null @@ -1,221 +0,0 @@ -.. image:: https://github.com/csdms/bmi-wavewatch3/raw/main/docs/source/_static/bmi-wavewatch3-logo-light.svg - :target: https://github.com/csdms/bmi-wavewatch3 - :alt: Python interface to WAVEWATCH III data - -WAVEWATCH III data in Python -============================ - -.. image:: https://github.com/csdms/bmi-wavewatch3/actions/workflows/test.yml/badge.svg - :target: https://github.com/csdms/bmi-wavewatch3/actions/workflows/test.yml - :alt: Test status - -.. image:: https://github.com/csdms/bmi-wavewatch3/workflows/Flake8/badge.svg - -.. image:: https://github.com/csdms/bmi-wavewatch3/workflows/Black/badge.svg - - -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. - -.. _WAVEWATCH III: https://polar.ncep.noaa.gov/waves -.. _Phase 1: https://polar.ncep.noaa.gov/waves/hindcasts/nopp-phase1.php -.. _Phase 2: https://polar.ncep.noaa.gov/waves/hindcasts/nopp-phase2.php -.. _Multigrid: https://polar.ncep.noaa.gov/waves/hindcasts/prod-multi_1.php -.. _Singlegrid: https://polar.ncep.noaa.gov/waves/hindcasts/prod-nww3.php - -.. end-abstract - -Installation ------------- - -To install the latest release of *bmi-wavewatch3* using *pip*, simply run the following -in your terminal of choice: - -.. code-block:: 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`_. - -.. _installation instructions: https://bmi-wavewatch3.readthedocs.io/en/master/installation.html - -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 - -Usage ------ - -.. start-usage - -To get started, you can download *WAVEWATCH III* data by date with the *ww3* command -(use `ww3 --help` to print a brief message), - -.. code-block:: bash - - ww3 fetch "2010-05-22" - -You can also do this through Python, - -.. code-block:: pycon - - >>> from bmi_wavewatch3 import WaveWatch3 - >>> WaveWatch3.fetch("2010-05-22") - -The *bmi_wavewatch3* package provides the ``WaveWatch3`` class for downloading data and -presenting it as an *xarray* *Dataset*. - -.. code-block:: pycon - - >>> from bmi_wavewatch3 import WaveWatch3 - >>> ww3 = WaveWatch3("2010-05-22") - >>> ww3.data - - ... - -Use the ``inc`` method to advance in time month-by-month, - -.. code-block:: pycon - - >>> ww3.date - '2010-05-22' - >>> ww3.inc() - '2010-06-22' - >>> ww3.data.time - - array('2010-06-01T00:00:00.000000000', dtype='datetime64[ns]') - ... - -This will download new datasets as necessary and load the new data into the ``data`` -attribute. - -.. note:: - - If the new data are not cached on you computer, you will notice a delay while the new - data are download. If the ``lazy`` flag is set, the download will only occur once you - try to access the data (i.e. ``ww3.data``), otherwise the data are downloaded - as soon as the date is set. - -Example -------- - -Plot data from the command line -``````````````````````````````` - -Running the following from the command line will plot the variable -*significant wave height* from the WAVEWATCH III *at_4m* grid. Note that the time of -day (in this case, 15:00) is separated from the date with a ``T`` (i.e. times can be -given as ``YYYY-MM-DDTHH``) - -.. code:: bash - - ww3 plot --grid=at_4m --data-var=swh "2010-09-15T15" - -.. image:: https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/hurricane_julia-light.png - :width: 100% - :alt: Hurricane Julia - :align: center - :class: only-light - -.. image:: https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/hurricane_julia-dark.png - :width: 100% - :alt: Hurricane Julia - :align: center - :class: only-dark - -.. end-usage - - -Plot data from Python -````````````````````` - -.. start-plotting - -This example is similar to the previous but uses the *bmi_wavewatch3* Python interface. - -.. code:: pycon - - >>> from bmi_wavewatch3 import WaveWatch3 - >>> ww3 = WaveWatch3("2009-11-08") - -The data can be accessed as an *xarray* *Dataset* through the ``data`` attribute. - -.. code:: pycon - - >>> ww3.data - - Dimensions: (step: 241, latitude: 311, longitude: 720) - Coordinates: - time datetime64[ns] 2009-11-01 - * step (step) timedelta64[ns] 0 days 00:00:00 ... 30 days 00:00:00 - surface float64 1.0 - * latitude (latitude) float64 77.5 77.0 76.5 76.0 ... -76.5 -77.0 -77.5 - * longitude (longitude) float64 0.0 0.5 1.0 1.5 ... 358.0 358.5 359.0 359.5 - valid_time (step) datetime64[ns] dask.array - Data variables: - dirpw (step, latitude, longitude) float32 dask.array - perpw (step, latitude, longitude) float32 dask.array - swh (step, latitude, longitude) float32 dask.array - u (step, latitude, longitude) float32 dask.array - v (step, latitude, longitude) float32 dask.array - Attributes: - GRIB_edition: 2 - GRIB_centre: kwbc - GRIB_centreDescription: US National Weather Service - NCEP - GRIB_subCentre: 0 - Conventions: CF-1.7 - institution: US National Weather Service - NCEP - history: 2022-06-08T16:08 GRIB to CDM+CF via cfgrib-0.9.1... - -The ``step`` attribute points to the current time slice into the data (i.e number of -three hour increments since the start of the month), - -.. code:: pycon - - >>> ww3.step - 56 - >>> ww3.data.swh[ww3.step, :, :].plot() - - -.. image:: https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/ww3_global_swh-light.png - :target: https://bmi-wavewatch3.readthedocs.org/ - :width: 100% - :alt: Significant wave height - :align: center - :class: only-light - -.. image:: https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/ww3_global_swh-dark.png - :target: https://bmi-wavewatch3.readthedocs.org/ - :width: 100% - :alt: Significant wave height - :align: center - :class: only-dark - -.. end-plotting - -.. _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 -.. _Singlegrid data: https://polar.ncep.noaa.gov/waves/hindcasts/nww3/ -.. _Multigrid data: https://polar.ncep.noaa.gov/waves/hindcasts/multi_1/ diff --git a/docs/source/authors.md b/docs/source/authors.md new file mode 100644 index 0000000..7c33aee --- /dev/null +++ b/docs/source/authors.md @@ -0,0 +1,2 @@ +```{include} ../../AUTHORS.md +``` diff --git a/docs/source/authors.rst b/docs/source/authors.rst deleted file mode 100644 index 7739272..0000000 --- a/docs/source/authors.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../AUTHORS.rst diff --git a/docs/source/changes.md b/docs/source/changes.md new file mode 100644 index 0000000..8b1749d --- /dev/null +++ b/docs/source/changes.md @@ -0,0 +1,2 @@ +```{include} ../../CHANGES.md +``` diff --git a/docs/source/changes.rst b/docs/source/changes.rst deleted file mode 100644 index d76c92b..0000000 --- a/docs/source/changes.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../CHANGES.rst diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 0000000..beda138 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,57 @@ +```{image} _static/bmi-wavewatch3-logo-light.svg +:align: center +:alt: Sequence +:class: only-light +:scale: 15% +:target: https://bmi-wavewatch3.readthedocs.org/ +``` + +```{image} _static/bmi-wavewatch3-logo-dark.svg +:align: center +:alt: Sequence +:class: only-dark +:scale: 15% +:target: https://bmi-wavewatch3.readthedocs.org/ +``` + +```{include} ../../README.md +:start-after: "% start-abstract" +:end-before: "% end-abstract" +``` + +```{image} _static/ww3_global_swh-light.png +:align: center +:alt: Significant wave height +:class: only-light +:target: https://bmi-wavewatch3.readthedocs.org/ +:width: 100% +``` + +```{image} _static/ww3_global_swh-dark.png +:align: center +:alt: Significant wave height +:class: only-dark +:target: https://bmi-wavewatch3.readthedocs.org/ +:width: 100% +``` + +```{toctree} +:caption: Getting Started +:hidden: true +:maxdepth: 2 + +install/index +usage +plotting +``` + +```{toctree} +:caption: Development +:hidden: true +:maxdepth: 2 + +Release Notes +Contributors +License +API Reference +``` diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index ba32de0..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. image:: _static/bmi-wavewatch3-logo-light.svg - :align: center - :scale: 15% - :alt: Sequence - :target: https://bmi-wavewatch3.readthedocs.org/ - :class: only-light - -.. image:: _static/bmi-wavewatch3-logo-dark.svg - :align: center - :scale: 15% - :alt: Sequence - :target: https://bmi-wavewatch3.readthedocs.org/ - :class: only-dark - - -.. include:: ../../README.rst - :start-after: .. start-abstract - :end-before: .. end-abstract - -.. image:: _static/ww3_global_swh-light.png - :target: https://bmi-wavewatch3.readthedocs.org/ - :width: 100% - :alt: Significant wave height - :align: center - :class: only-light - -.. image:: _static/ww3_global_swh-dark.png - :target: https://bmi-wavewatch3.readthedocs.org/ - :width: 100% - :alt: Significant wave height - :align: center - :class: only-dark - -.. toctree:: - :caption: Getting Started - :maxdepth: 2 - :hidden: - - install/index - usage - plotting - -.. toctree:: - :caption: Development - :maxdepth: 2 - :hidden: - - Release Notes - Contributors - License - API Reference diff --git a/docs/source/install/basic_install.md b/docs/source/install/basic_install.md new file mode 100644 index 0000000..177130d --- /dev/null +++ b/docs/source/install/basic_install.md @@ -0,0 +1,53 @@ +(basic-install)= + +# Installation + +:::{important} +The following commands will install *bmi-wavewatch3* into your current environment. +Although not necessary, we **highly recommend** you install bmi-wavewatch3 into its +own {ref}`virtual environment `. +::: + +In order to use *bmi-wavewatch3* you will first need Python. While not +necessary, we recommend using the +[Anaconda Python distribution](https://www.anaconda.com/distribution/) +as it provides a large number of third-party packages useful for +scientific computing. + +To install *bmi-wavewatch3*, simply run the following in your terminal of choice: + +```{eval-rst} +.. tab:: mamba + + .. code-block:: bash + + conda install mamba -c conda-forge + mamba install bmi-wavewatch3 -c conda-forge +``` + +```{eval-rst} +.. tab:: conda + + .. code-block:: bash + + conda install bmi-wavewatch3 -c conda-forge +``` + +```{eval-rst} +.. tab:: pip + + .. code-block:: bash + + pip install bmi-wavewatch3 +``` + +:::{important} +Due to an issue with the *eccodes* package, **Windows users and users of newer +versions of Python** may see an error when trying to run *bmi-wavewatch3* that has +been installed from PyPI (i.e. using the *pip* method above). If you encounter this +problem, try installing using *conda*/*mamba*. +::: + +If you would like the very latest development version of *bmi-wavewatch3* or want to +modify or contribute code to the *bmi-wavewatch3* project, you will need to do a +{ref}`developer installation ` of *bmi-wavewatch3* from source. diff --git a/docs/source/install/basic_install.rst b/docs/source/install/basic_install.rst deleted file mode 100644 index 4b4532e..0000000 --- a/docs/source/install/basic_install.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _basic_install: - -Installation -============ - -.. important:: - - The following commands will install *bmi-wavewatch3* into your current environment. - Although not necessary, we **highly recommend** you install bmi-wavewatch3 into its - own :ref:`virtual environment `. - -In order to use *bmi-wavewatch3* you will first need Python. While not -necessary, we recommend using the -`Anaconda Python distribution `_ -as it provides a large number of third-party packages useful for -scientific computing. - -To install *bmi-wavewatch3*, simply run the following in your terminal of choice: - -.. tab:: mamba - - .. code-block:: bash - - conda install mamba -c conda-forge - mamba install bmi-wavewatch3 -c conda-forge - -.. tab:: conda - - .. code-block:: bash - - conda install bmi-wavewatch3 -c conda-forge - -.. tab:: pip - - .. code-block:: bash - - pip install bmi-wavewatch3 - -.. important:: - - Due to an issue with the *eccodes* package, **Windows users and users of newer - versions of Python** may see an error when trying to run *bmi-wavewatch3* that has - been installed from PyPI (i.e. using the *pip* method above). If you encounter this - problem, try installing using *conda*/*mamba*. - -If you would like the very latest development version of *bmi-wavewatch3* or want to -modify or contribute code to the *bmi-wavewatch3* project, you will need to do a -:ref:`developer installation ` of *bmi-wavewatch3* from source. diff --git a/docs/source/install/environments.rst b/docs/source/install/environments.md similarity index 82% rename from docs/source/install/environments.rst rename to docs/source/install/environments.md index c53c84e..66f6262 100644 --- a/docs/source/install/environments.rst +++ b/docs/source/install/environments.md @@ -1,8 +1,6 @@ -.. _virtual_environments: +(virtual-environments)= -==================== -Virtual Environments -==================== +# Virtual Environments A virtual environment is a self-contained directory tree that contains a Python installation for a particular version of Python along with additional packages. @@ -15,6 +13,7 @@ environments created using *conda*/*mamba*, you can use either *conda*/*mamba* o *pip* to install additional packages, while *venv*-created environments should stick with *pip*. +```{eval-rst} .. tab:: mamba .. code-block:: bash @@ -22,25 +21,30 @@ should stick with *pip*. conda install mamba -c conda-forge mamba create -n bmi-wavewatch3 mamba activate bmi-wavewatch3 +``` +```{eval-rst} .. tab:: conda .. code-block:: bash conda create -n bmi-wavewatch3 conda activate bmi-wavewatch3 +``` +```{eval-rst} .. tab:: venv .. code-block:: bash python -m venv .venv source .venv/bin/activate +``` Note that you will need to activate this environment every time you want to use it in a new shell. Helpful links on managing virtual environments: -* `conda environments `_. -* `venv environments `_. +- [conda environments](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands). +- [venv environments](https://docs.python.org/3/tutorial/venv.html). diff --git a/docs/source/install/index.md b/docs/source/install/index.md new file mode 100644 index 0000000..82ae3af --- /dev/null +++ b/docs/source/install/index.md @@ -0,0 +1,12 @@ +```{include} basic_install.md +:start-after: "(basic-install)=" +``` + +```{toctree} +:caption: Installing +:hidden: true +:maxdepth: 2 + +source_install +environments +``` diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst deleted file mode 100644 index 2ea8717..0000000 --- a/docs/source/install/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. include:: basic_install.rst - :start-after: .. _basic_install: - -.. toctree:: - :caption: Installing - :maxdepth: 2 - :hidden: - - source_install - environments diff --git a/docs/source/install/source_install.rst b/docs/source/install/source_install.md similarity index 55% rename from docs/source/install/source_install.rst rename to docs/source/install/source_install.md index 80379f8..a58b57f 100644 --- a/docs/source/install/source_install.rst +++ b/docs/source/install/source_install.md @@ -1,42 +1,39 @@ -.. _install: +(install)= -================= -Developer Install -================= - -.. important:: - - The following commands will install *bmi-wavewatch3* into your current environment. - Although not necessary, we **highly recommend** you install bmi-wavewatch3 into its - own :ref:`virtual environment `. +# Developer Install +:::{important} +The following commands will install *bmi-wavewatch3* into your current environment. +Although not necessary, we **highly recommend** you install bmi-wavewatch3 into its +own {ref}`virtual environment `. +::: If you will be modifying code or contributing new code to *bmi-wavewatch3*, you will first need to get *bmi-wavewatch3*'s source code and then install *bmi-wavewatch3* from that code. -Source Install --------------- +## Source Install -.. start-install-source +% start-install-source *bmi-wavewatch3* is actively being developed on GitHub, where the code is freely available. If you would like to modify or contribute code, you can either clone our repository -.. code-block:: bash - - git clone git://github.com/csdms/bmi-wavewatch3.git - -or download the `zip file `_: +```bash +git clone git://github.com/csdms/bmi-wavewatch3.git +``` -.. code-block:: bash +or download the [zip file](https://github.com/csdms/bmi-wavewatch3/archive/refs/heads/main.zip): - curl -OL https://github.com/csdms/bmi-wavewatch3/archive/refs/heads/main.zip +```bash +curl -OL https://github.com/csdms/bmi-wavewatch3/archive/refs/heads/main.zip +``` Once you have a copy of the source code, you can install it into your current Python environment, +```{eval-rst} .. tab:: mamba .. code-block:: bash @@ -44,7 +41,9 @@ Python environment, cd bmi-wavewatch3 mamba install --file=requirements-conda.in pip install -e . +``` +```{eval-rst} .. tab:: conda .. code-block:: bash @@ -52,12 +51,15 @@ Python environment, cd bmi-wavewatch3 conda install --file=requirements-conda.in pip install -e . +``` +```{eval-rst} .. tab:: pip .. code-block:: bash cd bmi-wavewatch3 pip install -e . +``` -.. end-install-source +% end-install-source diff --git a/docs/source/license.md b/docs/source/license.md new file mode 100644 index 0000000..3064bc0 --- /dev/null +++ b/docs/source/license.md @@ -0,0 +1,2 @@ +```{include} ../../LICENSE.md +``` diff --git a/docs/source/license.rst b/docs/source/license.rst deleted file mode 100644 index 2f7644a..0000000 --- a/docs/source/license.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../LICENSE.rst diff --git a/docs/source/plotting.md b/docs/source/plotting.md new file mode 100644 index 0000000..3d58248 --- /dev/null +++ b/docs/source/plotting.md @@ -0,0 +1,6 @@ +# Plotting Output + +```{include} ../../README.md +:start-after: "% start-plotting" +:end-before: "% end-plotting" +``` diff --git a/docs/source/plotting.rst b/docs/source/plotting.rst deleted file mode 100644 index 2c907b5..0000000 --- a/docs/source/plotting.rst +++ /dev/null @@ -1,6 +0,0 @@ -Plotting Output -=============== - -.. include:: ../../README.rst - :start-after: .. start-plotting - :end-before: .. end-plotting diff --git a/docs/source/usage.md b/docs/source/usage.md new file mode 100644 index 0000000..6670175 --- /dev/null +++ b/docs/source/usage.md @@ -0,0 +1,6 @@ +# Usage + +```{include} ../../README.md +:start-after: "% start-usage" +:end-before: "% end-usage" +``` diff --git a/docs/source/usage.rst b/docs/source/usage.rst deleted file mode 100644 index 9e983f6..0000000 --- a/docs/source/usage.rst +++ /dev/null @@ -1,6 +0,0 @@ -Usage -===== - -.. include:: ../../README.rst - :start-after: .. start-usage - :end-before: .. end-usage From 2b15e69baa47b12b61c1bae639151aa196d2fb10 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 7 Sep 2023 18:09:52 -0600 Subject: [PATCH 02/15] add myst_parser extension --- docs/source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8c3ce7c..500cfc4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -53,6 +53,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "myst_parser", "sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.todo", @@ -141,3 +142,5 @@ towncrier_draft_autoversion_mode = "draft" # or: 'sphinx-release', 'sphinx-version' towncrier_draft_include_empty = True towncrier_draft_working_directory = pathlib.Path(docs_dir).parent.parent + +myst_enable_extensions = ["colon_fence"] From 24dbef50e7ee6e5bebf59cd255944d1b863cb6ed Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 7 Sep 2023 18:17:52 -0600 Subject: [PATCH 03/15] add myst-parser to requirements --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index 25d0fb5..63c29df 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ furo==2023.5.20 +myst-parser==2.0.0 pygments==2.14.0 sphinx==7.0.1 sphinx-copybutton==0.5.1 From ed64a4aadc5d1d984f7727464ba6ec092bcd813e Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 7 Sep 2023 18:18:05 -0600 Subject: [PATCH 04/15] update readthedocs config file --- .readthedocs.yaml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6871a5d..1b93bc7 100644 --- a/.readthedocs.yaml +++ b/.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 From a8fd22bb08f8a39b8115f911f8eee13edc636b7a Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 7 Sep 2023 18:38:34 -0600 Subject: [PATCH 05/15] set up towncrier for myst --- CHANGES.md | 4 +++- news/changelog_template.jinja | 15 ++++++++++++ pyproject.toml | 44 ++++++++++++++--------------------- 3 files changed, 35 insertions(+), 28 deletions(-) create mode 100644 news/changelog_template.jinja diff --git a/CHANGES.md b/CHANGES.md index d96a253..a9d2883 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,7 +4,9 @@ .. towncrier-draft-entries:: Not yet released ``` -% towncrier release notes start + + + ## 0.2.0 (2022-06-17) diff --git a/news/changelog_template.jinja b/news/changelog_template.jinja new file mode 100644 index 0000000..0cf429a --- /dev/null +++ b/news/changelog_template.jinja @@ -0,0 +1,15 @@ +{% if sections[""] %} +{% for category, val in definitions.items() if category in sections[""] %} + +### {{ definitions[category]['name'] }} + +{% for text, values in sections[""][category].items() %} +- {{ text }} {{ values|join(', ') }} +{% endfor %} + +{% endfor %} +{% else %} +No significant changes. + + +{% endif %} diff --git a/pyproject.toml b/pyproject.toml index dc1c22a..e072d14 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,7 @@ keywords = [ "data", "grib", ] -license = {file = "LICENSE.rst"} +license = {file = "LICENSE.md"} classifiers = [ "Development Status :: 4 - Beta", "Intended Audience :: Science/Research", @@ -50,9 +50,9 @@ dynamic = ["readme", "version"] [project.urls] homepage = "https://github.com/csdms" -documentation = "https://github.com/csdms/bmi-wave-watch-3/blob/main/README.rst" +documentation = "https://github.com/csdms/bmi-wave-watch-3/blob/main/README.md" repository = "https://github.com/csdms/bmi-wave-watch-3" -changelog = "https://github.com/csdms/bmi-wave-watch-3/blob/main/CHANGES.rst" +changelog = "https://github.com/csdms/bmi-wave-watch-3/blob/main/CHANGES.md" [project.optional-dependencies] dev = ["nox"] @@ -66,7 +66,7 @@ platforms = ["osx-arm64", "linux-64", "osx-64", "win-64"] [tool.setuptools.dynamic] -readme = {file = ["README.rst", "AUTHORS.rst"]} +readme = {file = ["README.md", "AUTHORS.md"]} version = {attr = "bmi_wavewatch3._version.__version__"} [tool.pytest.ini_options] @@ -97,28 +97,18 @@ line_length = 88 [tool.towncrier] directory = "news" package = "bmi_wavewatch3" -filename = "CHANGES.rst" +filename = "CHANGES.md" single_file = true -underlines = "-`^" -issue_format = "`#{issue} `_" -title_format = "{version} ({project_date})" +underlines = ["", "", ""] +start_string = "\n" +template = "news/changelog_template.jinja" +issue_format = "[#{issue}](https://github.com/csdms/bmi-wavewatch3/issues/{issue})" +title_format = "## [{version}](https://github.com/csdms/bmi-wavewatch3/tree/{version}) - {project_date}" -[[tool.towncrier.type]] -directory = "feature" -name = "New Features" -showcontent = true - -[[tool.towncrier.type]] -directory = "bugfix" -name = "Bug Fixes" -showcontent = true - -[[tool.towncrier.type]] -directory = "docs" -name = "Documentation Enhancements" -showcontent = true - -[[tool.towncrier.type]] -directory = "misc" -name = "Other Changes and Additions" -showcontent = true +type = [ + {name="New Tutorial Notebooks", directory="notebook", showcontent=true}, + {name="New Features", directory="feature", showcontent=true}, + {name="Bug Fixes", directory="bugfix", showcontent=true}, + {name="Documentation Enhancements", directory="docs", showcontent=true}, + {name="Other Changes and Additions", directory="misc", showcontent=true}, +] From e195d65ed3de41f13ba5699a0c35ae39424772b2 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 7 Sep 2023 19:07:52 -0600 Subject: [PATCH 06/15] add changes.md to the manifest --- MANIFEST.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MANIFEST.in b/MANIFEST.in index d9f49f0..400d9fa 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include CHANGES.rst +include CHANGES.md include CITATION.cff include .pre-commit-config.yaml include .python-version From a891520edd4d04fa9ce67735be382ce840e85053 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 7 Sep 2023 19:08:17 -0600 Subject: [PATCH 07/15] update pre-commit hooks --- .pre-commit-config.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 50e168a..0f7dfe1 100644 --- a/.pre-commit-config.yaml +++ b/.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", "."] From 302d749a6e9d9f4ead14122bffd8d33300e861be Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 11 Sep 2023 15:55:38 -0600 Subject: [PATCH 08/15] simplify the readme --- README.md | 185 +++++++----------------------------------------------- 1 file changed, 23 insertions(+), 162 deletions(-) diff --git a/README.md b/README.md index cf10a2d..f095b97 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,18 @@ -```{image} https://github.com/csdms/bmi-wavewatch3/raw/main/docs/source/_static/bmi-wavewatch3-logo-light.svg -:alt: Python interface to WAVEWATCH III data -:target: https://github.com/csdms/bmi-wavewatch3 -``` +[![Python interface to WAVEWATCH III data][logo]][github-link] + # WAVEWATCH III data in Python -```{image} https://github.com/csdms/bmi-wavewatch3/actions/workflows/test.yml/badge.svg -:alt: Test status -:target: https://github.com/csdms/bmi-wavewatch3/actions/workflows/test.yml -``` +[![Documentation status][rtd-badge]][rtd-link] +[![Code-style: Black][black-badge]][black-link] +[![Testing status][testing-badge]][testing-link] +![Flake8][flake8-badge] -```{image} https://github.com/csdms/bmi-wavewatch3/workflows/Flake8/badge.svg -``` - -```{image} https://github.com/csdms/bmi-wavewatch3/workflows/Black/badge.svg -``` ## 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. @@ -37,7 +31,9 @@ All data sources provide both global and regional grids. [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 @@ -57,153 +53,6 @@ If you would like to modify or contribute code to *bmi-wavewatch3* or use the ve latest development version, please see the documentation that describes how to [install bmi-wavewatch3 from source]. -## Usage - -% start-usage - -To get started, you can download *WAVEWATCH III* data by date with the *ww3* command -(use `ww3 --help` to print a brief message), - -```bash -ww3 fetch "2010-05-22" -``` - -You can also do this through Python, - -```pycon ->>> from bmi_wavewatch3 import WaveWatch3 ->>> WaveWatch3.fetch("2010-05-22") -``` - -The *bmi_wavewatch3* package provides the `WaveWatch3` class for downloading data and -presenting it as an *xarray* *Dataset*. - -```pycon ->>> from bmi_wavewatch3 import WaveWatch3 ->>> ww3 = WaveWatch3("2010-05-22") ->>> ww3.data - -... -``` - -Use the `inc` method to advance in time month-by-month, - -```pycon ->>> ww3.date -'2010-05-22' ->>> ww3.inc() -'2010-06-22' ->>> ww3.data.time - -array('2010-06-01T00:00:00.000000000', dtype='datetime64[ns]') -... -``` - -This will download new datasets as necessary and load the new data into the `data` -attribute. - -:::{note} -If the new data are not cached on you computer, you will notice a delay while the new -data are download. If the `lazy` flag is set, the download will only occur once you -try to access the data (i.e. `ww3.data`), otherwise the data are downloaded -as soon as the date is set. -::: - -## Example - -### Plot data from the command line - -Running the following from the command line will plot the variable -*significant wave height* from the WAVEWATCH III *at_4m* grid. Note that the time of -day (in this case, 15:00) is separated from the date with a `T` (i.e. times can be -given as `YYYY-MM-DDTHH`) - -```bash -ww3 plot --grid=at_4m --data-var=swh "2010-09-15T15" -``` - -```{image} https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/hurricane_julia-light.png -:align: center -:alt: Hurricane Julia -:class: only-light -:width: 100% -``` - -```{image} https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/hurricane_julia-dark.png -:align: center -:alt: Hurricane Julia -:class: only-dark -:width: 100% -``` - -% end-usage - -### Plot data from Python - -% start-plotting - -This example is similar to the previous but uses the *bmi_wavewatch3* Python interface. - -```pycon ->>> from bmi_wavewatch3 import WaveWatch3 ->>> ww3 = WaveWatch3("2009-11-08") -``` - -The data can be accessed as an *xarray* *Dataset* through the `data` attribute. - -```pycon ->>> ww3.data - -Dimensions: (step: 241, latitude: 311, longitude: 720) -Coordinates: - time datetime64[ns] 2009-11-01 - * step (step) timedelta64[ns] 0 days 00:00:00 ... 30 days 00:00:00 - surface float64 1.0 - * latitude (latitude) float64 77.5 77.0 76.5 76.0 ... -76.5 -77.0 -77.5 - * longitude (longitude) float64 0.0 0.5 1.0 1.5 ... 358.0 358.5 359.0 359.5 - valid_time (step) datetime64[ns] dask.array -Data variables: - dirpw (step, latitude, longitude) float32 dask.array - perpw (step, latitude, longitude) float32 dask.array - swh (step, latitude, longitude) float32 dask.array - u (step, latitude, longitude) float32 dask.array - v (step, latitude, longitude) float32 dask.array -Attributes: - GRIB_edition: 2 - GRIB_centre: kwbc - GRIB_centreDescription: US National Weather Service - NCEP - GRIB_subCentre: 0 - Conventions: CF-1.7 - institution: US National Weather Service - NCEP - history: 2022-06-08T16:08 GRIB to CDM+CF via cfgrib-0.9.1... -``` - -The `step` attribute points to the current time slice into the data (i.e number of -three hour increments since the start of the month), - -```pycon ->>> ww3.step -56 ->>> ww3.data.swh[ww3.step, :, :].plot() -``` - -```{image} https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/ww3_global_swh-light.png -:align: center -:alt: Significant wave height -:class: only-light -:target: https://bmi-wavewatch3.readthedocs.org/ -:width: 100% -``` - -```{image} https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/ww3_global_swh-dark.png -:align: center -:alt: Significant wave height -:class: only-dark -:target: https://bmi-wavewatch3.readthedocs.org/ -:width: 100% -``` - -% end-plotting [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 @@ -213,3 +62,15 @@ three hour increments since the start of the month), [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 From b058d0d6bf466ade6e167aafbcd8aed485a374da Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 11 Sep 2023 15:56:00 -0600 Subject: [PATCH 09/15] move plotting and usage sections into docs --- docs/source/plotting.md | 91 +++++++++++++++++++++++++++++++++++++++-- docs/source/usage.md | 49 ++++++++++++++++++++-- 2 files changed, 134 insertions(+), 6 deletions(-) diff --git a/docs/source/plotting.md b/docs/source/plotting.md index 3d58248..26193d6 100644 --- a/docs/source/plotting.md +++ b/docs/source/plotting.md @@ -1,6 +1,91 @@ # Plotting Output -```{include} ../../README.md -:start-after: "% start-plotting" -:end-before: "% end-plotting" +## Plot data from the command line + +Running the following from the command line will plot the variable +*significant wave height* from the WAVEWATCH III *at_4m* grid. Note that the time of +day (in this case, 15:00) is separated from the date with a `T` (i.e. times can be +given as `YYYY-MM-DDTHH`) + +```bash +ww3 plot --grid=at_4m --data-var=swh "2010-09-15T15" +``` + +```{image} _static/hurricane_julia-light.png +:align: center +:alt: Hurricane Julia +:class: only-light +:width: 75% +``` + +```{image} _static/hurricane_julia-dark.png +:align: center +:alt: Hurricane Julia +:class: only-dark +:width: 75% +``` + + +## Plot data from Python + + +This example is similar to the previous but uses the *bmi_wavewatch3* Python interface. + +```pycon +>>> from bmi_wavewatch3 import WaveWatch3 +>>> ww3 = WaveWatch3("2009-11-08") +``` + +The data can be accessed as an *xarray* *Dataset* through the `data` attribute. + +```pycon +>>> ww3.data + +Dimensions: (step: 241, latitude: 311, longitude: 720) +Coordinates: + time datetime64[ns] 2009-11-01 + * step (step) timedelta64[ns] 0 days 00:00:00 ... 30 days 00:00:00 + surface float64 1.0 + * latitude (latitude) float64 77.5 77.0 76.5 76.0 ... -76.5 -77.0 -77.5 + * longitude (longitude) float64 0.0 0.5 1.0 1.5 ... 358.0 358.5 359.0 359.5 + valid_time (step) datetime64[ns] dask.array +Data variables: + dirpw (step, latitude, longitude) float32 dask.array + perpw (step, latitude, longitude) float32 dask.array + swh (step, latitude, longitude) float32 dask.array + u (step, latitude, longitude) float32 dask.array + v (step, latitude, longitude) float32 dask.array +Attributes: + GRIB_edition: 2 + GRIB_centre: kwbc + GRIB_centreDescription: US National Weather Service - NCEP + GRIB_subCentre: 0 + Conventions: CF-1.7 + institution: US National Weather Service - NCEP + history: 2022-06-08T16:08 GRIB to CDM+CF via cfgrib-0.9.1... +``` + +The `step` attribute points to the current time slice into the data (i.e number of +three hour increments since the start of the month), + +```pycon +>>> ww3.step +56 +>>> ww3.data.swh[ww3.step, :, :].plot() +``` + +```{image} _static/ww3_global_swh-light.png +:align: center +:alt: Significant wave height +:class: only-light +:target: https://bmi-wavewatch3.readthedocs.org/ +:width: 100% +``` + +```{image} _static/ww3_global_swh-dark.png +:align: center +:alt: Significant wave height +:class: only-dark +:target: https://bmi-wavewatch3.readthedocs.org/ +:width: 100% ``` diff --git a/docs/source/usage.md b/docs/source/usage.md index 6670175..c336313 100644 --- a/docs/source/usage.md +++ b/docs/source/usage.md @@ -1,6 +1,49 @@ # Usage -```{include} ../../README.md -:start-after: "% start-usage" -:end-before: "% end-usage" +To get started, you can download *WAVEWATCH III* data by date with the *ww3* command +(use `ww3 --help` to print a brief message), + +```bash +ww3 fetch "2010-05-22" +``` + +You can also do this through Python, + +```pycon +>>> from bmi_wavewatch3 import WaveWatch3 +>>> WaveWatch3.fetch("2010-05-22") +``` + +The *bmi_wavewatch3* package provides the `WaveWatch3` class for downloading data and +presenting it as an *xarray* *Dataset*. + +```pycon +>>> from bmi_wavewatch3 import WaveWatch3 +>>> ww3 = WaveWatch3("2010-05-22") +>>> ww3.data + +... +``` + +Use the `inc` method to advance in time month-by-month, + +```pycon +>>> ww3.date +'2010-05-22' +>>> ww3.inc() +'2010-06-22' +>>> ww3.data.time + +array('2010-06-01T00:00:00.000000000', dtype='datetime64[ns]') +... ``` + +This will download new datasets as necessary and load the new data into the `data` +attribute. + +:::{note} +If the new data are not cached on you computer, you will notice a delay while the new +data are download. If the `lazy` flag is set, the download will only occur once you +try to access the data (i.e. `ww3.data`), otherwise the data are downloaded +as soon as the date is set. +::: From c1ece550d752d5cc6a3c38148ed720648afa9c6f Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 11 Sep 2023 15:56:36 -0600 Subject: [PATCH 10/15] add simple code snippet to index page --- docs/source/index.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index beda138..4b13108 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -15,8 +15,14 @@ ``` ```{include} ../../README.md -:start-after: "% start-abstract" -:end-before: "% end-abstract" +:start-after: "" +:end-before: "" +``` + +```pycon +>>> from bmi_wavewatch3 import WaveWatch3 +>>> ww3 = WaveWatch3("2009-11-08") +>>> ww3.data.swh[ww3.step, :, :].plot() ``` ```{image} _static/ww3_global_swh-light.png From b48bda75186208911726c6a4a135e951c4bb7c92 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 11 Sep 2023 15:57:43 -0600 Subject: [PATCH 11/15] remove eval-rst blocks --- docs/source/install/basic_install.md | 32 +++++++++------------- docs/source/install/environments.md | 39 ++++++++++++--------------- docs/source/install/source_install.md | 39 ++++++++++++--------------- 3 files changed, 47 insertions(+), 63 deletions(-) diff --git a/docs/source/install/basic_install.md b/docs/source/install/basic_install.md index 177130d..aa1863c 100644 --- a/docs/source/install/basic_install.md +++ b/docs/source/install/basic_install.md @@ -16,30 +16,24 @@ scientific computing. To install *bmi-wavewatch3*, simply run the following in your terminal of choice: -```{eval-rst} -.. tab:: mamba - - .. code-block:: bash - - conda install mamba -c conda-forge - mamba install bmi-wavewatch3 -c conda-forge +````{tab} mamba +```bash +conda install mamba -c conda-forge +mamba install bmi-wavewatch3 -c nodefaults -c conda-forge ``` +```` -```{eval-rst} -.. tab:: conda - - .. code-block:: bash - - conda install bmi-wavewatch3 -c conda-forge +````{tab} conda +```bash +conda install bmi-wavewatch3 -c nodefaults -c conda-forge ``` +```` -```{eval-rst} -.. tab:: pip - - .. code-block:: bash - - pip install bmi-wavewatch3 +````{tab} pip +```bash +pip install bmi-wavewatch3 ``` +```` :::{important} Due to an issue with the *eccodes* package, **Windows users and users of newer diff --git a/docs/source/install/environments.md b/docs/source/install/environments.md index 66f6262..f3fb881 100644 --- a/docs/source/install/environments.md +++ b/docs/source/install/environments.md @@ -13,33 +13,28 @@ environments created using *conda*/*mamba*, you can use either *conda*/*mamba* o *pip* to install additional packages, while *venv*-created environments should stick with *pip*. -```{eval-rst} -.. tab:: mamba - - .. code-block:: bash - - conda install mamba -c conda-forge - mamba create -n bmi-wavewatch3 - mamba activate bmi-wavewatch3 +````{tab} mamba +```bash +conda install mamba -c conda-forge +mamba create -n bmi-wavewatch3 +mamba activate bmi-wavewatch3 ``` +```` -```{eval-rst} -.. tab:: conda - - .. code-block:: bash - - conda create -n bmi-wavewatch3 - conda activate bmi-wavewatch3 +````{tab} conda +```bash +conda create -n bmi-wavewatch3 +conda activate bmi-wavewatch3 ``` +```` -```{eval-rst} -.. tab:: venv - - .. code-block:: bash - - python -m venv .venv - source .venv/bin/activate +````{tab} venv +```bash +python -m venv .venv +source .venv/bin/activate ``` +```` + Note that you will need to activate this environment every time you want to use it in a new shell. diff --git a/docs/source/install/source_install.md b/docs/source/install/source_install.md index a58b57f..f9fbbd4 100644 --- a/docs/source/install/source_install.md +++ b/docs/source/install/source_install.md @@ -33,33 +33,28 @@ curl -OL https://github.com/csdms/bmi-wavewatch3/archive/refs/heads/main.zip Once you have a copy of the source code, you can install it into your current Python environment, -```{eval-rst} -.. tab:: mamba - .. code-block:: bash - - cd bmi-wavewatch3 - mamba install --file=requirements-conda.in - pip install -e . +````{tab} mamba +```bash +cd bmi-wavewatch3 +mamba install --file=requirements-conda.in +pip install -e . ``` +```` -```{eval-rst} -.. tab:: conda - - .. code-block:: bash - - cd bmi-wavewatch3 - conda install --file=requirements-conda.in - pip install -e . +````{tab} conda +```bash +cd bmi-wavewatch3 +conda install --file=requirements-conda.in +pip install -e . ``` +```` -```{eval-rst} -.. tab:: pip - - .. code-block:: bash - - cd bmi-wavewatch3 - pip install -e . +````{tab} pip +```bash +cd bmi-wavewatch3 +pip install -e . ``` +```` % end-install-source From 27a68f182cdfdb6ffeec159b278e82e4760a2d29 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 11 Sep 2023 15:58:30 -0600 Subject: [PATCH 12/15] fix towncrier for markdown --- CHANGES.md | 4 ++-- pyproject.toml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index a9d2883..47ea891 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,7 +1,7 @@ # Release Notes -```{eval-rst} -.. towncrier-draft-entries:: Not yet released + +```{towncrier-draft-entries} Not yet released ``` diff --git a/pyproject.toml b/pyproject.toml index e072d14..342fd64 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -66,7 +66,7 @@ platforms = ["osx-arm64", "linux-64", "osx-64", "win-64"] [tool.setuptools.dynamic] -readme = {file = ["README.md", "AUTHORS.md"]} +readme = {file = ["README.md", "AUTHORS.md", "CHANGES.md"], content_type="text/markdown"} version = {attr = "bmi_wavewatch3._version.__version__"} [tool.pytest.ini_options] @@ -103,7 +103,7 @@ underlines = ["", "", ""] start_string = "\n" template = "news/changelog_template.jinja" issue_format = "[#{issue}](https://github.com/csdms/bmi-wavewatch3/issues/{issue})" -title_format = "## [{version}](https://github.com/csdms/bmi-wavewatch3/tree/{version}) - {project_date}" +title_format = "## {version} ({project_date})" type = [ {name="New Tutorial Notebooks", directory="notebook", showcontent=true}, From 0d9131af54e5dab8f0960f6521468d6cbda4eef0 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 11 Sep 2023 16:00:13 -0600 Subject: [PATCH 13/15] update furo version --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 63c29df..d6463df 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,4 @@ -furo==2023.5.20 +furo==2023.09.10 myst-parser==2.0.0 pygments==2.14.0 sphinx==7.0.1 From eb50298e579b167cf7c3ffb597b08420b8172ade Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 11 Sep 2023 16:23:57 -0600 Subject: [PATCH 14/15] fix subheadings --- docs/source/plotting.md | 4 ++-- docs/source/usage.md | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/plotting.md b/docs/source/plotting.md index 26193d6..1035ac0 100644 --- a/docs/source/plotting.md +++ b/docs/source/plotting.md @@ -1,6 +1,6 @@ # Plotting Output -## Plot data from the command line +## Command line Running the following from the command line will plot the variable *significant wave height* from the WAVEWATCH III *at_4m* grid. Note that the time of @@ -26,7 +26,7 @@ ww3 plot --grid=at_4m --data-var=swh "2010-09-15T15" ``` -## Plot data from Python +## Python This example is similar to the previous but uses the *bmi_wavewatch3* Python interface. diff --git a/docs/source/usage.md b/docs/source/usage.md index c336313..ff2618c 100644 --- a/docs/source/usage.md +++ b/docs/source/usage.md @@ -1,5 +1,7 @@ # Usage +## Command Line + To get started, you can download *WAVEWATCH III* data by date with the *ww3* command (use `ww3 --help` to print a brief message), @@ -7,6 +9,8 @@ To get started, you can download *WAVEWATCH III* data by date with the *ww3* com ww3 fetch "2010-05-22" ``` +## Python + You can also do this through Python, ```pycon From b27654ed29e9fd616d4bb2cfb2daa2d485e799cd Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 11 Sep 2023 17:12:07 -0600 Subject: [PATCH 15/15] add news fragment --- news/74.docs | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 news/74.docs diff --git a/news/74.docs b/news/74.docs new file mode 100644 index 0000000..1459587 --- /dev/null +++ b/news/74.docs @@ -0,0 +1,3 @@ + +Cleaned up the documentation and switched formats from reStructuredText to +MyST-flavored markdown.