Updated documentation to include release instructions, plus minor formatting updates (#502)

* set column width in tables, for use in latex

* added title clearpage

* Added instructions on building docs and running doctests

* changed the size of certain graphics

* added new sections to index

* changed RTD to github actions

* changed graphic size

* updated apidocs for timeoptions

* added release date

* added software release instructions

* minor update to docs

* Updated release instructions

* Updated release instructions

* added library section to the latex docs

* Removed version number from html title

Author: kaklise

documentation/conf.py

@@ -236,7 +236,7 @@ def setup(app):
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+html_title = "WNTR documentation"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
@@ -336,6 +336,11 @@ def setup(app):
 # The font size ('10pt', '11pt' or '12pt').
 'pointsize': '10pt',
 
+'maketitle': r'''
+\sphinxmaketitle
+\clearpage
+''',
+
 # Additional stuff for the LaTeX preamble.
 'preamble':  r'''
 \usepackage{tcolorbox}

documentation/developers.rst

@@ -48,24 +48,39 @@ WNTR is also tested on private servers using several large water utility network
 
 Documentation
 ---------------------
-WNTR includes a user manual that is built using the Read the Docs service.
+WNTR includes a user manual that is built using GitHub Actions.
 The user manual is automatically rebuilt each time changes are made to the code.
 The documentation is publicly available at https://usepa.github.io/WNTR/.
 The user manual includes an overview, installation instructions, simple examples, 
 and information on the code structure and functions.  
 WNTR includes documentation on the API for all 
-public functions, methods, and classes.
+public functions, methods, and classes using NumPy Style Python Docstrings.
 New content is marked `Draft`.
 Python documentation string formatting can be found at
 https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html
 
-To build the documentation locally, run the following command in a 
-command line/PowerShell prompt from the documentation directory::
+* To build HTML files of the documentation locally, run the following command in a 
+  command line/PowerShell prompt from the documentation directory::
 
-	make html
+	  make html
 
-HTML files are created in the ``documentation/_build/html`` directory.
-Open ``index.html`` to view the documentation.
+  HTML files are created in the ``documentation/_build/html`` directory.
+  Open ``index.html`` to view the HTML documentation in a browser.
+
+* To build Latex files of the documentation locally, run the following command in a 
+  command line/PowerShell prompt from the documentation directory::
+
+	  make latex
+
+  Latex files are created in the ``documentation/_build/latex`` directory.
+  Copy all the files into Overleaf and build wntr.tex to create a PDF.
+
+* To run the doctests locally, run the following command in a 
+  command line/PowerShell prompt from the documentation directory::
+  
+	  pytest --doctest-glob="*.rst" .
+
+  Note that this also creates graphics used in the documentation.
 
 Examples
 ---------------------
@@ -92,18 +107,131 @@ by opening a new issue on https://github.com/USEPA/WNTR/issues.
 
 Pull requests must meet the following minimum requirements to be included in WNTR:
 
-* Code is expected to be documented using Read the Docs.  
+* Code is expected to be documented using NumPy Style Python Docstrings.
 
 * Code is expected have sufficient tests.  `Sufficient` is judged by the strength of the test and code coverage. An 80% code coverage is recommended.  
 
 * Large files (> 1Mb) will not be committed to the repository without prior approval.
 
 * Network model files will not be duplicated in the repository.  Network files are stored in examples/network and wntr/tests/networks_for_testing only.
 
+Software release
+------------------
+The software release process requires administrative privileges and knowledge about the external services used in the release process.
+The release creates wheels that are available on PyPI and conda-forge.
+A release candidate (with version number rc1, rc2, ...) should be created prior to an official release.
+Changes to WNTR (Steps 1, 2, and 12) can be completed using pull requests, or through direct edits on GitHub.
+Since the release depends on external services, the instructions below often need slight modification between release cycles.
+
+1. **Check the version number**: The version number is defined in WNTR/wntr/__init__.py.  
+   The version number is denoted <version> in the instructions below and is in X.Y.Z format, where X is the major release number, 
+   Y is the minor release number, and Z is a bug fix release number.  
+   
+   If creating a release candidate, include rc1, rc2, etc at the end of the version number.
+
+2. **Check or create release notes**: The release notes are in WNTR/documentation/whatsnew/<version>.rst 
+   (see Step 3 to autogenerate release notes) and make sure the 
+   <version>.rst file is included in WNTR\documentation\whatsnew.rst.
+   Update the release date in <version>.rst.
+  
+3. **Create a new release on GitHub**: Go to https://github.com/USEPA/WNTR/releases and select “Draft a new release”.
+   Create a new tag (named <version>) and title (“Version <version> Release”).
+   Autogenerate release notes by selecting “Generate release notes”, clean up the text to have consistent language.  
+   The same text can go in <version>.rst.  
+   
+   If this is a release candidate, select "Set as a pre-release", otherwise select "Set as the latest release". 
+   Select "Publish release".  
+
+4. **Push wheels to PyPI**: The new release will initiate GitHub Actions to run workflows, 
+   this includes a step to push wheels to PyPI.
+   
+   If the wheels are not pushed to PyPI (because of the PyPI token or some other reason), 
+   download the artifact from the release (the file is named wntr-<version>.zip), unzip the file and use https://github.com/pypa/twine 
+   to upload the files to PyPI. See instructions at https://twine.readthedocs.io/.
+
+5. **Create a personal fork of the conda-forge wntr-feedstock**: 
+   The conda-forge wntr-feedstock is located at https://github.com/conda-forge/wntr-feedstock.
+   The personal fork will be named https://github.com/<username>/wntr-feedstock, 
+   where <username> is your github username.
+
+6. **Clone the wntr-feedstock and create a new branch**: Clone your personal fork of the wntr-feedstock and checkout a new branch.
+   For examples, the <branchname> could be named "release-<version>".  The following commands clone wntr-feedstock and create a branch::
+		
+      git clone https://github.com/<username>/wntr-feedstock.git
+      cd wntr-feedstock
+      git checkout –b <branchname>
+
+7. **Update the feedstock recipe**: The feedstock recipe is stored in wntr-feedstock/recipe/meta.yaml.
+   The following steps are needed to update the file.
+
+   a. Update the version number in ``{% set version = <version> %}``
+   
+   b. Update the source url to point to correct version in ``url: https://github.com/USEPA/WNTR/archive/<version>.zip``
+   
+   c. Update the SHA256 key in ``sha256: 78aa135219...``. 
+      Generate the SHA256 key for the source code archive using openssl. 
+      More info can be found at http://conda-forge.org/docs/maintainer/adding_pkgs.html or in the example 
+      recipe at https://github.com/conda-forge/staged-recipes/blob/master/recipes/example/meta.yaml.
+
+      Download the zip by copying and pasting the following address into a browser window::
+
+	     https://github.com/USEPA/WNTR/archive/<version>.zip
+		 
+      You should now have a downloaded file named WNTR-<version>.zip. 
+      Generate the SHA256 key by running the following command, in the same folder as the file::
+
+	     openssl sha256 WNTR-<version>.zip
+
+      Copy the resulting SHA256 key and paste it on the sha256 line.
+	  
+   d. Reset the build number to 0 in ``number: 0``. The build number only needs to be increased if a new build is needed for the same source version. 
+      See https://github.com/conda-forge/staged-recipes/wiki/Frequently-asked-questions. 
+   
+   e. Ensure requirements are correct.  Use pin compatibility to specify specific versions, for example::
+
+	    {{ pin_compatible('geopandas', upper_bound='1.0') }}
+	
+   f. Commit changes to meta.yml::
+   
+	     git commit -m "update meta.yaml" recipe/meta.yaml
+	  
+   g. Push changes to your fork/branch::
+
+	     git push <username> <branchname>
+
+10. **Render the feedstock recipe on conda-forge**: Create a pull request to https://github.com/conda-forge/wntr-feedstock. Review the checklist, 
+    and have the conda-forge-admin rerender the files by adding ``@conda-forge-admin, please rerender`` to the pull request.  
+    Once all tests have passed, merge the pull request. The pull request description should include the following checks and message for the conda-forge-admin:: 
+
+	   * [x] Used a personal fork of the feedstock to propose changes
+	   * [x] Bumped the build number (if the version is unchanged)
+	   * [x] Reset the build number to 0 (if the version changed)
+	   * [ ] Re-rendered with the latest conda-smithy 
+	   * [x] Ensured the license file is being packaged.
+	   @conda-forge-admin, please rerender
+
+11. **Test the release (or release candidate)**: Create a new conda environment with a WNTR supported version of Python and no default packages, 
+    and then install WNTR and then print the version number (pytest can also be run locally to further test the release).
+    To test the PyPI installation::
+    
+	   conda create --name test1 python=3.12 --no-default-packages
+	   conda activate test1
+	   pip install wntr
+	   python -c "import wntr; print(wntr.__version__)"
+    
+    To test the conda installation::
+    
+	   conda create --name test2 python=3.12 --no-default-packages
+	   conda activate test2
+	   conda install -c conda-forge wntr
+	   python -c "import wntr; print(wntr.__version__)"
+
+12. **Add an announcement to the homepage**: If this is not a release candidate, update attention.rst with an 
+    announcement for the new release (update version number).  This will update https://usepa.github.io/WNTR.
 
 Development team
 -------------------
 WNTR was developed as part of a collaboration between the United States 
-Environmental Protection Agency Office of Research and Development, 
-Sandia National Laboratories, and Purdue University.  
-See https://github.com/USEPA/WNTR/graphs/contributors for a full list of contributors.
+Environmental Protection Agency Office of Research and Development and
+Sandia National Laboratories.  
+See https://github.com/USEPA/WNTR/graphs/contributors for a full list of contributors.

documentation/disaster_models.rst

@@ -97,7 +97,7 @@ The earthquake properties can be plotted on the network using the following exam
 
 .. _fig-network:
 .. figure:: figures/network_pga.png
-   :width: 640
+   :width: 535
    :alt: Peak ground acceleration
 
    Peak ground acceleration.

documentation/fragility.rst

@@ -63,7 +63,7 @@ of exceeding the Minor damage state is 0.80.
 
 .. _fig-fragility:
 .. figure:: figures/fragility_curve.png
-   :width: 640
+   :width: 535
    :alt: Fragility curve
 
    Example fragility curve.
@@ -113,7 +113,7 @@ To plot the damage state on the network, the state (i.e., Major) can be converte
 
 .. _fig-damage-state:
 .. figure:: figures/damage_state.png
-   :width: 640
+   :width: 535
    :alt: Damage state
 
    Damage state, selected from the fragility curve.

documentation/framework.rst

@@ -26,6 +26,7 @@ run simulations are described in more detail below, followed by a list of softwa
 
 .. _table-wntr-subpackage:
 .. table:: WNTR Subpackages
+   :widths: 20 80
 
    =================================================  =============================================================================================================================================================================================================================================================================
    Subpackage                                         Description
@@ -51,7 +52,8 @@ Additionally, EPANET INP files can be generated from water network models.
 
 .. _table-network-subpackage:
 .. table:: Network Classes
-
+   :widths: 20 80
+   
    ==================================================  =============================================================================================================================================================================================================================================================================
    Class                                               Description
    ==================================================  =============================================================================================================================================================================================================================================================================
@@ -79,7 +81,8 @@ These classes are listed in :numref:`table-sim-subpackage`.
 
 .. _table-sim-subpackage:
 .. table:: Simulator Classes
-
+   :widths: 20 80
+   
    =================================================  =============================================================================================================================================================================================================================================================================
    Class                                              Description
    =================================================  =============================================================================================================================================================================================================================================================================

documentation/gis.rst

@@ -441,7 +441,7 @@ the hydrants snapped to the junctions in Net1.
 
 .. _fig-snap-points:
 .. figure:: figures/snap_points.png
-   :width: 640
+   :width: 535
    :alt: Hydrants snapped to junctions in EPANET example Net1 using the snapped points to points function
 
    Net1 with example hydrants snapped to junctions, in which the larger blue circles are the hydrant locations and the smaller red circles are the associated junctions.
@@ -526,7 +526,7 @@ illustrates the valve layer created by snapping points to lines in Net1.
 
 .. _fig-snap-lines:
 .. figure:: figures/snap_lines.png
-   :width: 640
+   :width: 535
    :alt: Isolation valves snapped to pipes in EPANET example Net1 using the snapped points to lines function
 
    Net1 with example valve layer created by snapping points to lines, in which the blue circles are the isolation valve locations 
@@ -631,7 +631,7 @@ The pipes are colored based upon their maximum earthquake probability.
 
 .. _fig-intersect-earthquake:
 .. figure:: figures/intersect_earthquake.png
-   :width: 640
+   :width: 535
    :alt: Intersection of pipes with earthquake fault lines in EPANET example Net1
 
    Net1 with example earthquake fault lines intersected with pipes, which are colored based upon their maximum earthquake probability.  
@@ -716,7 +716,7 @@ The pipes are colored based upon their weighted mean landslide probability.
 
 .. _fig-intersect-landslide:
 .. figure:: figures/intersect_landslide.png
-   :width: 640
+   :width: 535
    :alt: Intersection of junctions with landslide zones in EPANET example Net1
 
    Net1 with example landslide zones intersected with pipes, which are colored based upon their weighted mean landslide probability. 
@@ -825,7 +825,7 @@ the census tracts (polygons) is different than the junction and pipe attributes.
 
 .. _fig-intersect-demographics:
 .. figure:: figures/intersect_demographics.png
-   :width: 640
+   :width: 535
    :alt: Intersection of junctions and pipes with mean income demographic data in EPANET example Net1
 
    Net1 with mean income demographic data intersected with junctions and pipes.
@@ -923,7 +923,7 @@ sampled from the raster file.
 
 .. _fig-sample-elevations:
 .. figure:: figures/sample_elevations.png
-   :width: 640
+   :width: 535
    :alt: Net1 with elevations sampled from raster.
 
    Net1 with elevations sampled from raster.

documentation/graphics.rst

@@ -67,7 +67,7 @@ which can be further customized by the user.
 
 .. _fig-network-2:
 .. figure:: figures/plot_basic_network.png
-   :width: 640
+   :width: 535
    :alt: Network
 
    Basic network graphic.
@@ -151,7 +151,7 @@ The following example plots the network along with node population (:numref:`fig
 
 .. _fig-plotly:
 .. figure:: figures/plot_plotly_network.png
-   :width: 640
+   :width: 535
    :alt: Network
 
    Interactive network graphic with the legend showing the node population.
@@ -181,7 +181,7 @@ with pipe length over the city of Albuquerque (for demonstration purposes only)
 
 .. _fig-leaflet:
 .. figure:: figures/interactive_network.png
-   :width: 640
+   :width: 535
    :alt: Network
 
    Interactive Leaflet network graphic.
@@ -236,7 +236,7 @@ The following example plots simulation results from above, showing pressure at a
 
 .. _fig-timeseries:
 .. figure:: figures/plot_timeseries.png
-   :width: 640
+   :width: 535
    :alt: Network
 
    Time series graphic.
@@ -273,7 +273,7 @@ The following example uses simulation results from above, and converts the graph
 
 .. _fig-interactive-timeseries:
 .. figure:: figures/interactive_timeseries.png
-   :width: 640
+   :width: 535
    :alt: Network
 
    Interactive time series graphic with the tank heights for Tank 1 (blue), Tank 2 (orange), and Tank 3 (green).
@@ -305,7 +305,7 @@ The following example plots a fragility curve with two states (:numref:`fig-frag
 
 .. _fig-fragility2:
 .. figure:: figures/fragility_curve.png
-   :width: 640
+   :width: 535
    :alt: Fragility curve
 
    Fragility curve graphic.
@@ -338,7 +338,7 @@ The following example plots a pump curve (:numref:`fig-pump`).
 
 .. _fig-pump:
 .. figure:: figures/plot_pump_curve.png
-   :width: 640
+   :width: 535
    :alt: Pump curve
 
    Pump curve graphic.
@@ -429,7 +429,7 @@ The valves and valve segments are plotted on the network (:numref:`fig-valve_seg
 
 .. _fig-valve_segment:
 .. figure:: figures/plot_valve_segment.png
-   :width: 640
+   :width: 535
    :alt: Valve segment attributes
 
    Valves layer and segments.
@@ -457,7 +457,7 @@ valves surrounding each valve is plotted on the network
 
 .. _fig-valve_segment_attributes:
 .. figure:: figures/plot_valve_segment_attributes.png
-   :width: 640
+   :width: 535
    :alt: Valve segment attributes
 
    Valve segment attribute showing the number of valves surrounding each valve.