Documentation Samples

[DanielHabenicht]

I am very new to WNTR and EPANET simulations (or water networks in general) and was wondering if it might be possible to add code examples to the documentation (meaning some of the functions).

As I have a computer science background I came across this library which should integrate nicely with the documentation system already in place and insure that the examples will work: https://docs.python.org/3/library/doctest.html

For example:

wn = wntr.network.WaterNetworkModel()
wn.add_reservoir(
    "R1",  # Name of the reservoir
    base_head=52, # Head in meters
    coordinates=(0, 1) # Tuple for positioning
)

or

wn = wntr.network.WaterNetworkModel()
wn.add_pipe(
    "P1",  # Pipe Name
    "J1",  # Junction A to connect to
    "J2",  # Junction B 
    length=2000, # Lenght of the Pipe in meters
    diameter=0.6, # Diameter of the Pipe in meters
    roughness=0.00026 # Roughness of the pipe in Meter (D-W) or Unitless (H-W) 
)

My goal with this issue would be to make it easier for users to understand which unit format they have to use (it's clear that everything is in SI, but still getting a feeling for the right scale is nice).

[kaklise]

Thanks for the suggestion. We use doctest throughout the documentation RST files to include code samples and to ensure the code samples are tested. However, we have tried to limit the use of additional comments in the code blocks and rely on the surrounding text to describe the class/method/function. This seems to match the style of other python package user guides.

The API documentation includes additional detail, but there is always room for improvement (for example, see https://wntr.readthedocs.io/en/latest/apidoc/wntr.network.model.html#wntr.network.model.WaterNetworkModel.add_pipe). Units could be added to the descriptions. We try to link the documentation to the API class/method/function when it's first introduced.

[DanielHabenicht]

All right, so I won't add any examples to the class/method/function documentation but will look out to improve the guides instead and try to link the class/method/function with each other. Thanks!

Should I just create PR's for each change or bundle them?
I already have some changes just from mistakes I made during my first tries:

• https://github.com/USEPA/WNTR/compare/main...DanielHabenicht:WNTR:main?expand=1
• https://github.com/USEPA/WNTR/compare/main...DanielHabenicht:WNTR:patch-1?expand=1

[kaklise]

Those additions look great. Feel free to bundle minor updates together. We can always add review comments by line if we need to iterate on wording.