From 8fe871143a889ced92af26d6d56fa05e964904f3 Mon Sep 17 00:00:00 2001 From: Chris Leaman Date: Sat, 4 May 2019 15:00:46 +1000 Subject: [PATCH 1/3] Update documentation --- Makefile | 2 ++ README.rst | 4 ++-- docs/background.rst | 52 +++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 10 ++++++++- docs/index.rst | 47 +++++++++++++++++++++++++------------- docs/installation.rst | 10 +++++++++ docs/models.rst | 12 ++++++++++ docs/usage.rst | 14 ++++++++++++ 8 files changed, 133 insertions(+), 18 deletions(-) create mode 100644 docs/background.rst create mode 100644 docs/installation.rst create mode 100644 docs/models.rst create mode 100644 docs/usage.rst diff --git a/Makefile b/Makefile index edf5fe8..3705d32 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,5 @@ +.PHONY: install docs update-requirements bump + install: poetry install diff --git a/README.rst b/README.rst index 9c52657..d1b79d6 100644 --- a/README.rst +++ b/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 diff --git a/docs/background.rst b/docs/background.rst new file mode 100644 index 0000000..0bd10eb --- /dev/null +++ b/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. diff --git a/docs/conf.py b/docs/conf.py index 7caddc3..98bb79e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,7 +30,12 @@ # 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,9 @@ pygments_style = "sphinx" +html_sidebars = { + "**": ["globaltoc.html", "relations.html", "sourcelink.html", "searchbox.html"] +} # Autodoc options diff --git a/docs/index.rst b/docs/index.rst index 0a60a46..9a57520 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,23 +1,40 @@ -.. 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 + + +Contents +~~~~~~~~ .. toctree:: :maxdepth: 2 - :caption: Contents: -.. automodule:: models - :members: - :undoc-members: + background + installation + usage + models +.. -Indices and tables -================== + Empirical wave runup models implemented in Python for coastal engineers and scientists. -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..7bcbffd --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,10 @@ + +Installation +------------ + +Installation of ``py-wave-runup`` can be done with pip: + +.. code:: bash + + pip install py-wave-runup + diff --git a/docs/models.rst b/docs/models.rst new file mode 100644 index 0000000..6b9a857 --- /dev/null +++ b/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: diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..1e1b185 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,14 @@ + +Usage +----- + +.. code:: python + + from py_wave_runup import models + + model_sto06 = models.Stockdon2006(Hs=4, Tp=12, beta=0.1) + + model_sto06.R2 # 2.54 + model_sto06.setup # 0.96 + model_sto06.sinc # 2.06 + model_sto06.sig # 1.65 From af5233a12143910477c815b76d865e201ec7f951 Mon Sep 17 00:00:00 2001 From: Chris Leaman Date: Sun, 5 May 2019 14:46:03 +1000 Subject: [PATCH 2/3] Update documentation --- Makefile | 1 + docs/conf.py | 14 +++++++++++++- docs/index.rst | 7 +++++-- docs/installation.rst | 17 ++++++++++++++++- docs/usage.rst | 17 ++++++++++++++++- 5 files changed, 51 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 3705d32..452e74d 100644 --- a/Makefile +++ b/Makefile @@ -14,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" ############################### diff --git a/docs/conf.py b/docs/conf.py index 98bb79e..f3d96e3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,7 +23,7 @@ author = "Chris Leaman" # The full version, including alpha/beta/rc tags -release = "v0.1.1" +release = "v0.1.2" # -- General configuration --------------------------------------------------- @@ -70,6 +70,18 @@ "**": ["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 # Define what classes to skip diff --git a/docs/index.rst b/docs/index.rst index 9a57520..54756da 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,6 +22,11 @@ Python Wave Runup :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 ~~~~~~~~ @@ -36,5 +41,3 @@ Contents .. - Empirical wave runup models implemented in Python for coastal engineers and scientists. - diff --git a/docs/installation.rst b/docs/installation.rst index 7bcbffd..1f16b57 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,9 +2,24 @@ Installation ------------ -Installation of ``py-wave-runup`` can be done with pip: +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. diff --git a/docs/usage.rst b/docs/usage.rst index 1e1b185..7d10103 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,13 +1,28 @@ - Usage ----- +First, make sure that the package is :doc:`installed `. + +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 +` 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 From 3171a1dae8de8b8e08e364251e303026ac94199c Mon Sep 17 00:00:00 2001 From: Chris Leaman Date: Sun, 5 May 2019 14:52:46 +1000 Subject: [PATCH 3/3] Bump version --- docs/conf.py | 2 +- py_wave_runup/__init__.py | 2 +- pyproject.toml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index f3d96e3..d29d206 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,7 +23,7 @@ author = "Chris Leaman" # The full version, including alpha/beta/rc tags -release = "v0.1.2" +release = "v0.1.3" # -- General configuration --------------------------------------------------- diff --git a/py_wave_runup/__init__.py b/py_wave_runup/__init__.py index b3f4756..ae73625 100644 --- a/py_wave_runup/__init__.py +++ b/py_wave_runup/__init__.py @@ -1 +1 @@ -__version__ = "0.1.2" +__version__ = "0.1.3" diff --git a/pyproject.toml b/pyproject.toml index f8b41fb..d6341d4 100644 --- a/pyproject.toml +++ b/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+"