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.
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.
Activate the environment, if not already active:
conda activate watertap-dev
Enter the directory where your local clone of the WaterTAP repository is located, and pull the latest changes using
cd /path/to/your/clone git pull
Uninstall the version of
watertapthat’s currently installed in the environment:
pip uninstall watertap
pip installcommand targeting the
pip --no-cache-dir install -r requirements-dev.txt
--no-cache-dirflag 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:
pandocis 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
Change directory to the “docs” subdirectory
Generate the HTML with Sphinx.
On Windows, run
On Linux/OSX run
After these steps are complete, you should be able to preview the HTML documentation by opening the file
_build/html/index.html in a web browser.
API docs (autogenerated)
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.,
unit_models — of the
docs/technical_reference section (and folder). See
for an example.
Reference documentation for the code is generated automatically from the Python functions, classes, and modules in the
watertap package by
To refer to the documentation for a particular function, class, or module, use the
:mod: reference syntax respectively.
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.util.examples.flowsheets.full_treatment_train.check_build`
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
: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.