How to contribute to WaterTAP’s development

Installing WaterTAP in an existing development environment

When either the watertap package or one of its dependencies are installed, it should be possible to update those packages within an existing developer environment.

Important

In case of any issue or unexpected behavior when updating an existing environment, first try to see if the issues are solved if a freshly created environment is used instead.

  1. Activate the environment, if not already active:

    conda activate watertap-dev

  2. Enter the directory where your local clone of the WaterTAP repository is located, and pull the latest changes using git pull:

    cd /path/to/your/clone
git pull

  3. Uninstall the version of watertap that’s currently installed in the environment:

    pip uninstall watertap

  4. Run the pip install command targeting the requirements-dev.txt file.

    pip --no-cache-dir install -r requirements-dev.txt

    Note

    The --no-cache-dir flag is used to ensure that existing packages are not erroneously reused by pip, which would cause the wrong (outdated) version to be present in the environment after installation.

Working with the WaterTAP documentation

The project documentation is created and updated using the Sphinx documentation tool. This tool generates nice, indexed, HTML webpages — like this one — from text files in the “docs” directory. The documentation will include the docstrings you put on your modules, classes, methods, and functions as well as additional documentation in text files in the “docs” directory. The project is set up so that Sphinx documentation is generated automatically online for new releases. This section describes how to do this same documentation generation locally in your development environment so you can preview what will be shown to the users.

Generating the documentation

To generate a local copy of the documentation for the first time, follow these steps:

  1. Install the pandoc executable. As pandoc is a standalone tool rather than a Python package, it cannot be installed using pip. Instead, use one of the following options:

    • If using a Conda environment, run conda install -c conda-forge pandoc

    • Alternatively, refer to the installation steps appropriate for your system on pandoc’s website

  2. Change directory to the “docs” subdirectory

  3. Generate the HTML with Sphinx.

    • On Windows, run .\make html

    • On Linux/OSX run make html

After these steps are complete, you should be able to preview the HTML documentation by opening the file located at _build/html/index.html in a web browser.

API docs (autogenerated)

The sphinx-apidoc tool is used to automatically generate documentation pages for the WaterTAP API from the docstrings defined in the source code of the watertap Python package.

sphinx-apidoc is invoked automatically by the Sphinx build process, so no extra manual steps should be necessary. After building the HTML docs using the steps described above in Generating the documentation, the generated API docs pages can be accessed by browsing to the “Technical Reference” page and clicking on the “Module Reference” link.

Updating the documentation

If you edited some documentation directly, i.e. created or modified a text file with extension .rst, then you will need to update the documentation with the build command given in step 3 of Generating the documentation.

Documenting your modules

Full documentation for modules should be placed in the appropriate subfolder — e.g., property_models or unit_models — of the docs/technical_reference section (and folder). See docs/technical_reference/unit_models/reverse_osmosis_0D.rst for an example.

Reference documentation for the code is generated automatically from the Python functions, classes, and modules in the watertap package by sphinx-apidoc. To refer to the documentation for a particular function, class, or module, use the :func:, :class:, or :mod: reference syntax respectively.

Note

More information on referencing Python objects in Sphinx, see the Sphinx documentation section on the Python domain

The following examples show how to add a small paragraph to the end of a document to provide links to the relevant parts of the codebase:

Module Documentation
--------------------

- :mod:`watertap.unit_models.reverse_osmosis_0D`

Class Documentation
-------------------

- :class:`watertap.unit_models.reverse_osmosis_0D.ReverseOsmosis0D`

Or, for multiple code reference types in the same paragraph:

Code Documentation
------------------

- :mod:`watertap.unit_models.reverse_osmosis_0D`
- :class:`watertap.unit_models.reverse_osmosis_0D.ReverseOsmosis0D`
- :func:`watertap.core.util.scaling.transform_property_constraints`

Linking to the reference documentation pages for the relevant module/class/function(s) in this way is usually enough for the majority of cases.

Special use case: displaying code documentation inside another page

If for some reason it is necessary or desirable to display the code in the document itself (i.e. as opposed to linking to a separate page), the .. automodule:: directive can be used:

.. automodule:: watertap.unit_modules.reverse_osmosis_0D
    :members:
    :noindex:

The meaning of the options is the following:

  • :noindex: (required): prevents the creation of an index entry

  • :members:: include all the classes, functions, etc. in the module

Warning

The :noindex: option must be specified to avoid conflicts with the autogenerated entry. Forgetting to add :noindex: will result in warnings being emitted during the Sphinx build process. If the code is being submitted as a Pull Request (PR), the warnings will cause a failure in the automatic checks enforced as part of the WaterTAP Continuous Integration (CI) suite.