Added documentation pages

CHANGELOG.md

@@ -5,7 +5,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
-
+### Added
+- Documentation pages
+### Changed
+- Set github actions for publishing packages automatically
 
 ## [0.0.5] - 2020-12-03
 ### Added

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+We'd love to accept your patches and contributions to this project. There are just a few small 
+guidelines you need to follow.
+
+## Guidelines
+1. Write your patch
+1. Add a test case to your patch
+1. Make sure that all tests run properly
+1. Send your patch as a PR
+
+## Installation
+
+You can install the WandaToolbox package as follows:
+```
+pip install wandatoolbox 
+```
+
+## Development installation and testing
+
+For development you can use the 'editable' installation:
+```
+pip install -e . 
+pytest
+```
+
+## Building the package
+
+Building the backage is done as follows:
+```
+pip install setuptools wheel
+python setup.py sdist bdist_wheel
+```
+
+## Creating a release
+
+We use bump2version to update the version numbers. Bump2version will also create a tag and commit the 
+changes.  This can then be pushed using
+```
+git push origin <branch> --tags
+```
+The Github Actions have been configured to run the tests and flake8 linting and publish to test.Pypi 
+on every push. If a commit is also tagged it will also publish to Pypi. 

README.md

@@ -3,10 +3,12 @@
 [![Documentation Status](https://readthedocs.org/projects/wandatoolbox/badge/?version=latest)](https://wandatoolbox.readthedocs.io/en/latest/?badge=latest)
 
 # Wanda Toolbox
-Toolbox (python scripts) for Wanda modellers
+Toolbox (python scripts) for Wanda modellers. This toolbox includes several tools and utilities that can help with Wanda modelling, 
+running simulations and analyzing and visualizing simulation results. This module is closely related to PyWanda, the Python bindings for the Wanda API.
 
-This toolbox includes several tools and utilities that can help with Wanda modelling and 
-running simulations. 
+Wanda is an advanced water hammer software, designed for engineers by engineers. The Python API bindings can be used to create Wanda models, 
+run simulations, and extract the simulation results. The Wanda Toolbox module includes additional scripts to go beyond the basic data retrieval of pywanda.
+
 
 ## Installation
 Run the following to install this package:
@@ -18,62 +20,8 @@ pip install WandaToolbox
 Also see: https://pypi.org/project/wandatoolbox/
 
 ## Usage
-Generic usage of the WandaPlot classes:
-```python
-from wandatoolbox.wanda_plot import PlotSyschar, PlotText, PlotTable, PlotImage, plot
-import matplotlib.pyplot as plt
-from matplotlib.backends.backend_pdf import PdfPages
-import pandas as pd
-import pywanda as pw
+Tutorial and reference documentation is provided at [wandatoolbox.readthedocs.io](https://wandatoolbox.readthedocs.io). A PDF version of the manual is available [here](https://wandatoolbox.readthedocs.io/_/downloads/en/latest/pdf/). And the source code is always available at [https://github.com/MichielTukker/WandaToolbox](github.com/MichielTukker/WandaToolbox).
 
-model = pw.WandaModel(r'c:\Wandamodel.wdi', 'c:\Wanda 4.6\Bin\\')
-
-with PdfPages(f'Document.pdf') as pdf:
-    img = plt.imread('WandaToolbox\data\DELTARES_ENABLING_CMYK.png')
-    df = pd.read_excel(r'example_data\syschar_test.xlsx', header=0, index_col=0)
-    scenario_names = ["Current min", "Current max", "Future min", "Future max"]
-
-    subplots_table = [
-        PlotTable(df, ['description', "Current min", "Current max", "Future min", "Future max"]), 
-        PlotImage(img), PlotText("Yada yada yada"), 
-        PlotSyschar("BOUNDQ B1", 105.0, "Supplier #1", df, 'Wanda_name', 
-        scenario_names, 3, "Industry description", 'Discharge (m3/day)', 'Head (m)')
-    ]
-    plot(model, subplots_table,
-         'Main title',
-         f'Subtitle 1',
-         'Subtitle 2',
-         'Subtitle 3',
-         'Subtitle 4',
-         f'Figure number: 1',
-         company_image=plt.imread('WandaToolbox\data\DELTARES_ENABLING_CMYK.png'),
-         fontsize=10)
-    pdf.savefig()
-    plt.close()
-```
-
-Generic usage of the monte-carlo class:
-```python
-from wandatoolbox.analysis.monte_carlo import MonteCarloInputProperty, MonteCarloOutputProperty, WandaMonteCarlo
-import pywanda as pw
-import os
-
-def main():
-    wandacase_fullpath = os.path.join(os.getcwd(), "Sewage_transient.wdi")
-    wanda_bin_directory = r'c:\Program Files (x86)\Deltares\Wanda 4.6\Bin\\'
-    model = pw.WandaModel(wandacase_fullpath, wanda_bin_directory)
-    parameters = [MonteCarloInputProperty(" PIPES", "Wall roughness", 2.5 / 1000, 0.5 / 1000, "normal", True)]
-    outputs = [MonteCarloOutputProperty(" PIPES", "Pressure", keyword=True, extreme="MIN"),
-               MonteCarloOutputProperty(" PIPES", "Pressure", keyword=True, extreme="MAX")]
-    analysis = WandaMonteCarlo(model, parameters, outputs, nruns=25, n_workers=2)
-    analysis.run()
-    analysis.plot_results(filename_prefix="test", width=1000, height=800)
-    analysis.cleanup()
-
-
-if __name__ == "__main__":
-    main()  # This main() method is essential due to the way Python's multiprocessing module works
-```
-# Support
+## Support
 No official support! For questions/improvements/comments, contact Deltares or Wanda support desk?
 

docs/advanced/analysis.rst

@@ -0,0 +1,31 @@
+analysis tools
+===============
+
+Monte-carlo analysis
+--------------------
+Generic usage of the monte-carlo class:
+
+.. code-block:: python
+    :linenos:
+
+    from wandatoolbox.analysis.monte_carlo import MonteCarloInputProperty, MonteCarloOutputProperty, WandaMonteCarlo
+    import pywanda as pw
+    import os
+
+    def main():
+        wandacase_fullpath = os.path.join(os.getcwd(), "Sewage_transient.wdi")
+        wanda_bin_directory = r'c:\Program Files (x86)\Deltares\Wanda 4.6\Bin\\'
+        model = pw.WandaModel(wandacase_fullpath, wanda_bin_directory)
+        parameters = [MonteCarloInputProperty(" PIPES", "Wall roughness", 2.5 / 1000, 0.5 / 1000, "normal", True)]
+        outputs = [MonteCarloOutputProperty(" PIPES", "Pressure", keyword=True, extreme="MIN"),
+                MonteCarloOutputProperty(" PIPES", "Pressure", keyword=True, extreme="MAX")]
+        analysis = WandaMonteCarlo(model, parameters, outputs, nruns=25, n_workers=2)
+        analysis.run()
+        analysis.plot_results(filename_prefix="test", width=1000, height=800)
+        analysis.cleanup()
+
+
+    if __name__ == "__main__":
+        main()  # This main() method is essential due to the way Python's multiprocessing module works
+
+The monte carlo toolset will run multiple simulation in parallel, greatly reducing the simulation time. 

docs/advanced/callibration.rst

@@ -0,0 +1,2 @@
+Callibration
+=============

docs/advanced/optimization.rst

@@ -0,0 +1,2 @@
+Optimization
+=============

docs/contributing.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../CONTRIBUTING.md

docs/figures.rst

@@ -0,0 +1,44 @@
+Plotting figures
+========================================
+
+Usage
+--------
+WandaToolbox supports plotting various objects to a formatted PDF, which can be included as an appendix in your 
+report. WandaToolbox.wanda_plot supports time and location series where data is exported directly from Wanda models. 
+It also supports adding tables, images or text blocks on pages, and supports generating system characteristics for 
+a range of flow rates and discharge points.
+
+Code example:
+
+.. code-block:: python
+    :linenos:
+    
+    from wandatoolbox.wanda_plot import PlotSyschar, PlotText, PlotTable, PlotImage, plot
+    import matplotlib.pyplot as plt
+    from matplotlib.backends.backend_pdf import PdfPages
+    import pandas as pd
+    import pywanda as pw
+
+    model = pw.WandaModel(r'c:\Wandamodel.wdi', 'c:\Wanda 4.6\Bin\\')
+    img = plt.imread('WandaToolbox\data\DELTARES_ENABLING_CMYK.png')
+    df = pd.read_excel(r'example_data\syschar_test.xlsx', header=0, index_col=0)
+    scenario_names = ["Current min", "Current max", "Future min", "Future max"]
+
+    with PdfPages(f'Document.pdf') as pdf:
+        subplots_table = [
+            PlotTable(df, ['description', "Current min", "Current max", "Future min", "Future max"]), 
+            PlotImage(img), PlotText("Yada yada yada"), 
+            PlotSyschar("BOUNDQ B1", 105.0, "Supplier #1", df, 'Wanda_name', 
+            scenario_names, 3, "Industry description", 'Discharge (m3/day)', 'Head (m)')
+        ]
+        plot(model, subplots_table,
+            'Main title',
+            f'Subtitle 1',
+            'Subtitle 2',
+            'Subtitle 3',
+            'Subtitle 4',
+            f'Figure number: 1',
+            company_image=plt.imread('WandaToolbox\data\DELTARES_ENABLING_CMYK.png'),
+            fontsize=10)
+        pdf.savefig()
+        plt.close()

docs/index.rst

@@ -3,16 +3,39 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to WandaToolbox's documentation!
+WandaToolbox documentation!
 ========================================
 
+.. include:: readme.rst
+
+
+Contents
+============
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
 
-   members
-   readme
    changelog
+   contributing
+
+
+.. toctree::
+   :caption: The Basics
+   :maxdepth: 1
+
+   figures
+   paramterscript
+   miscellaneous
+
+
+.. toctree::
+   :caption: Advanced Topics
+   :maxdepth: 1
+
+   advanced/analysis
+   advanced/callibration
+   advanced/optimization
+
+
 
 
 Indices and tables

docs/miscellaneous.rst

@@ -0,0 +1,2 @@
+Misc. functions and tools
+========================================

docs/paramterscript.rst

@@ -0,0 +1,2 @@
+Parameterscript
+========================================

docs/readme.rst

@@ -1,6 +1,2 @@
-=================
-README
-=================
-
 .. mdinclude:: ../README.md