.. _developer-guide: 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. #. Activate the environment, if not already active: .. code-block:: shell conda activate watertap-dev #. Enter the directory where your local clone of the WaterTAP repository is located, and pull the latest changes using ``git pull``: .. code-block:: shell cd /path/to/your/clone git pull #. Uninstall the version of ``watertap`` that's currently installed in the environment: .. code-block:: shell pip uninstall watertap #. Run the ``pip install`` command targeting the ``requirements-dev.txt`` file. .. code-block:: shell 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. .. _documentation-mini-guide: 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. .. _documentation-mini-guide-gen: Generating the documentation ++++++++++++++++++++++++++++ To generate a local copy of the documentation for the first time, follow these steps: #. 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 `_ #. Change directory to the "docs" subdirectory #. 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 :ref:`documentation-mini-guide-gen`, the generated API docs pages can be accessed by browsing to the "Technical Reference" page and clicking on the "Module Reference" link. .. _documentation-mini-guide-update: 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 :ref:`documentation-mini-guide-gen`. 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.