Documentation: update README and add developer guide (#293)

* began restructuring documentation

* documented setup and branching

* documented DDD, TDD, Git commands

* document sphinx, actions, codecov; pypi desc

* fix install-python-pip link

* document codecov, PRs, releases

* troubleshoot sphinx docs

* manual write to gh-pages

* match docs and readme, start documenting pipenv

* fix docs workflow

* document pipenv, doc conventions, python testing

* make html in pipenv

* add design, core, research examples to readme

* fix image path

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,8 @@
 **Pull request recommendations:**
-- [ ] Name your pull request _your-development-type/short-description_. Ex: _feature/validate_floc_
-- [ ] Link to any relevant issue in the PR description. Ex: _Resolves [gh-12], adds flocculator validation_
-- [ ] Provide context of changes.
-- [ ] Provide relevant tests for your feature or bug fix.
-- [ ] Provide or update documentation for any feature added by your pull request.
+- Name your pull request {your development type}: {short description}. Ex: _Feature: flocculator validation_
+- Link to any relevant issue in the PR description. Ex: _Resolves #12, adds flocculator validation_
+- Provide context of changes.
+- Provide relevant tests for your feature or bug fix.
+- Provide or update documentation for any feature added by your pull request.
 
 Thanks for contributing!

.github/workflows/build.yml

@@ -51,13 +51,12 @@ jobs:
         python -m pip install --upgrade pip
         pip install pipenv
         pipenv install --dev
-        pip install sphinx_rtd_theme
         
     - name: Run doctests and build html files
       run: |
         cd docs
         pipenv run make doctest
-        make html
+        pipenv run make html
 
     - name: Run html-proofer
       uses: chabad360/htmlproofer@master

.github/workflows/docs.yml

@@ -1,9 +1,8 @@
 name: Documentation
 
 on:
-  push:
-    branches:
-      - 'master'
+  release:
+    types: [published]
 
 jobs:
   publish_docs:
@@ -20,12 +19,13 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install sphinx_rtd_theme
+        pip install pipenv
+        pipenv install --dev
         
     - name: Build Sphinx documentation
       run: |
         cd docs
-        make html
+        pipenv run make html
 
     - name: Publish Sphinx documentation
       uses: peaceiris/actions-gh-pages@v3

.gitignore

@@ -104,6 +104,7 @@ cov_html
 
 # Sphinx documentation
 docs/_build/
+docs/source/_build/
 venv/
 *.iml
 .idea/

README.md

@@ -1,86 +1,94 @@
-# aguaclara [![Build Status](https://github.com/AguaClara/aguaclara/workflows/Build/badge.svg)](https://github.com/AguaClara/aguaclara/actions) [![Documentation](https://github.com/AguaClara/aguaclara/workflows/Documentation/badge.svg)](https://aguaclara.github.io/aguaclara/) [![codecov](https://codecov.io/gh/AguaClara/aguaclara/branch/master/graph/badge.svg)](https://codecov.io/gh/AguaClara/aguaclara)
+# `aguaclara`
+[![Pypi Version](https://img.shields.io/pypi/v/aguaclara?color=blue&label=PyPI)](https://pypi.org/project/aguaclara/)
+[![Documentation](https://github.com/AguaClara/aguaclara/workflows/Documentation/badge.svg)](https://aguaclara.github.io/aguaclara/) 
+[![Build Status](https://github.com/AguaClara/aguaclara/workflows/Build/badge.svg)](https://github.com/AguaClara/aguaclara/actions) 
+[![Code Coverage](https://codecov.io/gh/AguaClara/aguaclara/branch/master/graph/badge.svg)](https://app.codecov.io/gh/AguaClara/aguaclara/)
 
+`aguaclara` is a Python package developed by [AguaClara Cornell](http://aguaclara.cornell.edu/) and [AguaClara Reach](https://www.aguaclarareach.org/) for designing and performing research on AguaClara water treatment plants. The package has several main functionalities:
 
-Design an AguaClara Water Treatment Plant with just a couple lines of code! Or just design a few components - your choice with aguaclara. aguaclara parametrically designs plant components from basic physics equations. In a nutshell, you can generate a design yaml for a whole plant and print it to your console stream like so:
+* **DESIGN** of AguaClara water treatment plant components
+* **MODELING** of physical, chemical, and hydraulic processes in water treatment
+* **PLANNING** of experimental setup for water treatment research
+* **ANALYSIS** of data collected by [ProCoDA](https://monroews.github.io/EnvEngLabTextbook/ProCoDA/ProCoDA.html) (process control and data acquisition tool)
 
-```python
-from aguaclara.play import *
-from aide_render import render
-import sys
-my_plant = Plant(HP(30, u.L/u.s))
-render(my_plant, sys.stdout)
-```
 
 ## Installing
+The `aguaclara` package can be installed from Pypi by running the following command in the command line:
+
 ```bash
 pip install aguaclara
 ```
+To upgrade an existing installation, run 
 
-## Installing as a developer
-If you want to make pushes to aguaclara, then you should clone this repo and make the package available locally, using the following commands:
 ```bash
-git clone https://github.com/AguaClara/aguaclara.git
-cd aguaclara
-pip install --editable . -U --user
+pip install aguaclara --upgrade
 ```
-The editable flag makes it so that you don't have to continuously install with pip to make the changes you just made visible.
 
-### Running Tests
-To run the test suite, you'll have to install the dev dependencies with pipenv from the repo root directory:
-```bash
-pipenv install 
+## Using `aguaclara`
+`aguaclara`'s main functionalities come from several sub-packages.
+
+1. **Core**: fundamental physical, chemical, and hydraulic functions and values
+2. **Design**: modules for designing components of an AguaClara water treatment plant
+3. **Research**: modules for process modeling, experimental design, and data analysis in AguaClara research
+
+To use `aguaclara`'s registry of scientific units (based on the [Pint package](https://pint.readthedocs.io/en/latest/)), use `from aguaclara.core.units import u`. Any other function or value in a sub-package can be accessed by importing the package itself:
+
+### Example Usage: Design
+```python
+import aguaclara as ac
+from aguaclara.core.units import u
+
+# Design a water treatment plant
+plant = ac.Plant(
+    q = 40 * u.L / u.s,
+    cdc = ac.CDC(coag_type = 'pacl'),
+    floc = ac.Flocculator(hl = 40 * u.cm),
+    sed = ac.Sedimentor(temp = 20 * u.degC),
+    filter = ac.Filter(q = 20 * u.L / u.s)
+)
 ```
-If pipenv reports you need to install a different version of python, please do so. After pipenv runs successfully, you'll have a fully provisioned testing environment. To run all the tests, now just type:
-```bash
-pipenv run pytest
+
+### Example Usage: Core
+```python
+# continued from Example Usage: Design
+
+# Model physical, chemical, and hydraulic properties 
+cdc = plant.cdc
+coag_tube_reynolds_number = ac.re_pipe(
+    FlowRate = cdc.coag_q_max,
+    Diam = cdc.coag_tube_id,
+    Nu = cdc.coag_nu(cdc.coag_stock_conc, cdc.coag_type)
+)
+```
+
+### Example Usage: Research
+```python
+import aguaclara as ac
+from aguaclara.core.units import u
+import matplotlib.pyplot as plt
+
+# Plan a research experiment
+reactor = ac.Variable_C_Stock(
+    Q_sys = 2 * u.mL / u.s, 
+    C_sys = 1.4 * u.mg / u.L, 
+    Q_stock = 0.01 * u.mL / u.s
+)
+C_stock_PACl = reactor.C_stock()
+
+# Visualize and analyze ProCoDA data
+ac.iplot_columns(
+    path = "https://raw.githubusercontent.com/AguaClara/team_resources/master/Data/datalog%206-14-2018.xls", 
+    columns = [3, 4], 
+    x_axis = 0
+)
+plt.ylabel("Turbidity (NTU)")
+plt.xlabel("Time (hr)")
+plt.legend(("Influent", "Effluent"))
 ```
-The tests should all pass. If they don't, check in with the latest Travis build of master to see what the difference between the Travis environment and your local environment could make the tests not pass.
-
-## Contributing: (v0.0.1 -> v0.1.0)
-1. Write your code!
-2. When you are ready to commit it, make a new branch that describes your changes and push it to github:
-    ```bash
-    $ git add . #add local files to staging area
-    $ git checkout -b the_name_of_my_new_branch #create new branch locally and move to it
-    $ git commit -m "my detailed commit message describing what I did" #commit to the new branch
-    $ git push -u origin the_name_of_my_new_branch #push the new branch and all the commits you made to GitHub.
-    ```
-3. Keep making changes and committing them as you finish your feature. Once you are ready to push your code to the master branch, go online and make a pull request to the master branch.
-4. The pull request will initiate several 'checks.' This will take about 5 minutes to run. The first is the Travis CI check. Travis is a cloud-based continuous integration tool that automatically runs all defined tests. Once the tests pass, Travis generates a coverage report. This report analyzed what percentage of the code was "hit" during the testing process, also known as what percentage was 'covered'.
-5. If all the checks passed, you can ping a repo manager to ask them to accept your pull request.
-6. If the repo manager accepts the request, then the next time a version of master is tagged as a release version, the code will be packaged as a source distribution (sdist) and sent off to [pypi](https://pypi.org/search/?q=aguaclara).
-
-## Changelog
-**aguaclara design is in RAPID development. Things will shange significantly!**
-
-We're not tracking changes at the moment here. Once development is at a more reasonable pace, we'll start tracking improvements and bug fixes more carefully!
-
-## Structure
-The aguaclara package has three distinct levels that work together to design a plant. The first level is composed of base classes that define chemicals, quantities, and other parameters. These classes are created and used within the functional layer to define some basic engineering equations. Lastly, the component classes correspond to objects that are modeled in Fusion 360.
-
-    +----------------------------+
-    | COMPONENT CLASSES (.parts) |
-    +-------------+              |
-    | Classes that correspond to |
-    | Fusion components.         |    ^
-    +------------+---------------+    |
-                 ^                    |
-                 |                    |
-    +-----------------------+         |
-    |  FUNCTIONAL|LAYER     |         | Each layer
-    +--------------+        |         | depends on the
-    |  This layer has only  |         | layers below
-    |  functions that rely  |         | it to function.
-    |  on quantity class    |         |
-    |  inputs.              |         |
-    +------------+----------+         |
-                 ^                    |
-                 |                    |
-    +------------+---------------+    |
-    |BASE CLASSES                |    |
-    +-----------                 |    |
-    |Classes needed to make the  |    |
-    |functional and component    |    +
-    |class layers work. Such as  |
-    |Quantity, HP and DP.        |
-    +----------------------------+
+
+The package is still undergoing rapid development. As it becomes more stable, a user guide will be written with more detailed tutorials. At the moment, you can find some more examples in specific pages of the [API reference](https://aguaclara.github.io/aguaclara/api.html).
+
+## Contributing
+Bug reports, features requests, documentation updates, and any other enhancements are welcome! To suggest a change, [make an issue](https://github.com/AguaClara/aguaclara/issues/new/choose) in the [`aguaclara` Github repository](https://github.com/AguaClara/aguaclara>).
+
+To contribute to the package as a developer, refer to the [Developer Guide](https://aguaclara.github.io/aguaclara/guide-dev/guide-dev.html).

codecov.yml

@@ -1,3 +1,5 @@
 ignore:
-  - "docs"
-  - "aguaclara/play.py"
+  - docs
+  - tests
+  - aguaclara/play.py
+  - setup.py

docs/source/api.rst

@@ -0,0 +1,14 @@
+.. _api:
+
+=============
+API Reference
+=============
+
+The following pages document the modules, functions, and values available in each sub-package.
+
+.. toctree::
+    :maxdepth: 2
+
+    core/core
+    design/design
+    research/research

docs/source/core/constants.rst

@@ -1,3 +1,5 @@
+.. _constants:
+
 Constants
 =========
 

docs/source/core/units.rst

@@ -1,3 +1,5 @@
+.. _units:
+
 Units
 =====