Merge branch 'develop'

Makefile

@@ -1,3 +1,5 @@
+.PHONY: install docs update-requirements bump
+
 install:
  poetry install
 
@@ -12,6 +14,7 @@ update-requirements:
 bump:
  poetry version
  @echo "Remember to increase version in py_wave_runup/__init__.py"
+ @echo "and in docs/conf.py"
 
 
 ###############################

README.rst

@@ -21,8 +21,8 @@ Python Wave Runup
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
  :target: https://github.com/ambv/black
 
-.. image:: https://pyup.io/repos/github/chrisleaman/py-wave-runup/shield.svg
- :target: https://pyup.io/repos/github/chrisleaman/py-wave-runup/
+.. image:: https://api.dependabot.com/badges/status?host=github&identifier=180274721
+ :target: https://dependabot.com
  :alt: Updates
 
 

docs/background.rst

@@ -0,0 +1,52 @@
+
+Background
+----------
+
+Wave runup refers to the final part of a wave's journey as it travels from offshore
+onto the beach. It is observable by anyone who goes to the beach and watches the edge
+of the water "runup" and rundown the beach. It is comprised of two components:
+
+ - **setup**: the height of the time averaged superelevation of the mean water level
+ above the Still Water Level (SWL)
+ - **swash**: the height of the time varying fluctuation of the instantaneous water
+ level about the setup elevation
+
+Setup, swash and other components of Total Water Level (TWL) rise are shown in this
+handy figure below.
+
+.. image:: ./_static/VitousekDoubling2017Fig1.jpg
+..
+
+ | Figure from Vitousek et al. (2017) [#vit17]_
+
+Wave runup can contribute a significant portion of the increase in TWL in coastal
+storms causing erosion and inundation. For example, Stockdon et al. (2006) [#sto06]_
+collated data from numerous experiments, some of which showed wave runup 2% excedence
+heights in excess of 3 m during some storms.
+
+Given the impact such a large increase in TWL can have on coastlines, there has been
+much research conducted to try improve our understanding of wave runup processes.
+Although there are many processes which can influence wave runup (such as nonlinear
+wave transformation, wave reflection, three-dimensional effects, porosity, roughness,
+permeability and groundwater) [#cem06]_, many attempts have been made to derive
+empirical relatinoships based on easily measurable parameters. Typically, empirical
+wave runup models include:
+
+ - **Hs**: significant wave height
+ - **Tp**: peak wave length
+ - **beta**: beach slope
+
+This python package attempts to consolidate the work done by others in this field and
+collate the numerous empirical relationships for wave runup which have been published.
+
+--------
+
+.. [#vit17] Vitousek, Sean, Patrick L. Barnard, Charles H. Fletcher, Neil Frazer,
+ Li Erikson, and Curt D. Storlazzi. "Doubling of Coastal Flooding Frequency
+ within Decades Due to Sea-Level Rise." Scientific Reports 7, no. 1 (May 18,
+ 2017): 1399. https://doi.org/10.1038/s41598-017-01362-7.
+.. [#sto06] Stockdon, Hilary F., Robert A. Holman, Peter A. Howd, and Asbury H. Sallenger.
+ "Empirical Parameterization of Setup, Swash, and Runup." Coastal Engineering 53,
+ no. 7 (May 1, 2006): 573-88. https://doi.org/10.1016/j.coastaleng.2005.12.005
+.. [#cem06] United States, Army, and Corps of Engineers. Coastal Engineering Manual.
+ Washington, D.C.: U.S. Army Corps of Engineers, 2006.

docs/conf.py

@@ -23,14 +23,19 @@
 author = "Chris Leaman"
 
 # The full version, including alpha/beta/rc tags
-release = "v0.1.1"
+release = "v0.1.3"
 
 
 # -- General configuration ---------------------------------------------------
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.mathjax", "sphinx.ext.napoleon"]
+extensions = [
+ "sphinx.ext.autodoc",
+ "sphinx.ext.mathjax",
+ "sphinx.ext.napoleon",
+ "sphinx.ext.autosummary",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -61,6 +66,21 @@
 
 pygments_style = "sphinx"
 
+html_sidebars = {
+ "**": ["globaltoc.html", "relations.html", "sourcelink.html", "searchbox.html"]
+}
+
+html_sidebars = {
+ "**": ["about.html", "navigation.html", "relations.html", "searchbox.html"]
+}
+
+html_theme_options = {
+ "description": "Empirical wave runup models implemented in Python for coastal engineers and scientists.",
+ "github_user": "chrisleaman",
+ "github_repo": "py-wave-runup",
+ "fixed_sidebar": True,
+ "github_button": True,
+}
 
 # Autodoc options
 

docs/index.rst

@@ -1,23 +1,43 @@
-.. py-wave-runup documentation master file, created by
- sphinx-quickstart on Wed Apr 10 15:13:58 2019.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
+Python Wave Runup
+=================
 
-Welcome to py-wave-runup's documentation!
-=========================================
+
+.. image:: https://img.shields.io/pypi/v/py-wave-runup.svg
+ :target: https://pypi.python.org/pypi/py-wave-runup
+
+.. image:: https://img.shields.io/travis/com/chrisleaman/py-wave-runup.svg
+ :target: https://travis-ci.com/chrisleaman/py-wave-runup
+
+.. image:: https://readthedocs.org/projects/py-wave-runup/badge/?version=latest
+ :target: https://py-wave-runup.readthedocs.io/en/latest/?badge=latest
+ :alt: Documentation Status
+
+.. image:: https://codecov.io/gh/chrisleaman/py-wave-runup/branch/master/graph/badge.svg
+ :target: https://codecov.io/gh/chrisleaman/py-wave-runup
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+ :target: https://github.com/ambv/black
+
+.. image:: https://api.dependabot.com/badges/status?host=github&identifier=180274721
+ :target: https://dependabot.com
+ :alt: Updates
+
+**py-wave-runup** is a Python module which makes it easy for coastal engineers and
+scientists to test and use various empirical wave runup models which have been
+published in literature.
+
+To get started, check out the sections below:
+
+Contents
+~~~~~~~~
 
 .. toctree::
  :maxdepth: 2
- :caption: Contents:
-
-.. automodule:: models
- :members:
- :undoc-members:
 
+ background
+ installation
+ usage
+ models
 
-Indices and tables
-==================
+..
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/installation.rst

@@ -0,0 +1,25 @@
+
+Installation
+------------
+
+If you don't have Python installed, Anaconda_ is an easy way to get up and running with Python.
+
+.. _Anaconda: https://docs.anaconda.com/anaconda/install/
+
+
+Installation of ``py-wave-runup`` can be done with ``pip``. Run this command in your
+terminal of choice to grab the latest release of this package:
+
+.. code:: bash
+
+ pip install py-wave-runup
+
+If you've installed an older version and want to upgrade to the latest version, run
+this command:
+
+.. code:: bash
+
+ pip install --upgrade py-wave-runup
+
+After you're up and running, head on over to :doc:`usage` for some examples of what
+you can do.

docs/models.rst

@@ -0,0 +1,12 @@
+Wave runup models
+=========================
+
+The following empirical wave parameterizations are made available in this module:
+
+- :class:`models.Stockdon2006`
+
+------------
+
+.. automodule:: models
+ :members:
+ :undoc-members:

docs/usage.rst

@@ -0,0 +1,29 @@
+Usage
+-----
+
+First, make sure that the package is :doc:`installed <installation>`.
+
+Now, we import the ``models`` module from ``py_wave_runup``. This is where all our
+empirical wave runup models are stored.
+
+.. code:: python
+
+ from py_wave_runup import models
+
+Then, we can pick a model from the :doc:`list of available wave runup models
+<models>` to use. Here we defined the wave height, wave period and slope used to
+calculate runup using the Stockdon et al. (2006) model.
+
+.. code:: python
+
+ model_sto06 = models.Stockdon2006(Hs=4, Tp=12, beta=0.1)
+
+Our model now gives us access to our wave runup parameter which have been calculated
+using the model.
+
+.. code:: python
+
+ model_sto06.R2 # 2.54
+ model_sto06.setup # 0.96
+ model_sto06.sinc # 2.06
+ model_sto06.sig # 1.65

py_wave_runup/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.2"
+__version__ = "0.1.3"

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "py-wave-runup"
-version = "0.1.2"
+version = "0.1.3"
 description = "Empirical wave runup models implemented in Python"
 authors = ["Chris Leaman"]
 license = "GPL-3.0+"