Edit the Wiki

Whenever a module is edited or created, please add it to or edit it in the wiki. For this purpose:

  1. Clone the River Architect Wiki: git clone https://github.com/RiverArchitect/RA_wiki.git

  2. Modify the wiki markdown files which are located in RA_wiki/wiki/*.md (see conventions and documenting a new module)

  3. If necessary, edit the sidebar located in RA_wiki/_includes/own/sidebar.html

  4. Push changes:

git add .
git commit -m "Leave a message"
git pull --rebase
git push

Please note: if git pull --rebase encounters problems, issues will be highlighted in the edited markdown / HTML files.

Documentation conventions

For editing markdown documents, we recommend using Notepad++ with Editoria’s markdown syntax style. Please be graphically descriptive and add figures to facilitate understanding your coding brilliance. For adding images, upload them to the River Architect Media/images (yes, you will need to clone this repository, too - read more about using git). Images can then be implemented in markdown file with:

![img_name](https://github.com/RiverArchitect/Media/raw/master/images/NEW_IMAGE.PNG)

Finally, please use grammar and spell checker before pushing changes.

Document a new module

For adding new module documentation, create a new markdown file (e.g., RA_wiki/wiki/NewModule.md). Describe the new module in the following order:

  1. Overview

  2. QuickGuide (normal usage - please add screenshots)

  3. Output (Products)

  4. Detailed descriptions / extended usage (e.g., equations and technical details)

Document Warning and Error messages prompted in try: - except: statements with self.logger.info("ERROR: Message") (see example in the module development Wiki). When writing new code, it is better to use precise exception rules such as except ValueError:. We often use the broad “shotgun” approach with except: only because we encountered unexpected exception types using arcpy. A better and future way of error message logging in River Architect will be to use self.logger.error() in the exception statement rather than self.logger.info(), which should exclusively be used to log calculation progress. Important is to add error messages, as well as warning messages, to the Troubleshooting Wiki. Use warning messages when a function can still work even though a variable assignment error occurred such as when an optional, additional raster is missing.