Merge pull request #393 from dbhart/docs-theme

Docs theme
USEPA · Nov 16, 2023 · 7c5a6a0 · 7c5a6a0
2 parents 733feed + 68136ed
commit 7c5a6a0
Show file tree

Hide file tree

Showing 116 changed files with 1,521 additions and 935 deletions.
diff --git a/.gitignore b/.gitignore
@@ -20,3 +20,5 @@ temp*
 examples/*.inp
 wntr/tests/*.png
 
+documentation/_local
+documentation/apidoc
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <h1>
-<img src="https://raw.githubusercontent.com/usepa/wntr/main/documentation/figures/logo.jpg" width="375">
+<img src="https://raw.githubusercontent.com/usepa/wntr/main/documentation/_static/logo.jpg" width="375">
 </h1><br>
 
 [![build](https://github.com/USEPA/WNTR/workflows/build/badge.svg)](https://github.com/USEPA/WNTR/actions/workflows/build_tests.yml)

diff --git a/documentation/_static/epa_logo.png b/documentation/_static/epa_logo.png
diff --git a/documentation/figures/logo.jpg → documentation/_static/logo.jpg b/documentation/figures/logo.jpg → documentation/_static/logo.jpg
diff --git a/documentation/_static/snl_logo.png b/documentation/_static/snl_logo.png
diff --git a/documentation/_static/wntr-favicon.svg b/documentation/_static/wntr-favicon.svg
diff --git a/documentation/_templates/autosummary/base.rst b/documentation/_templates/autosummary/base.rst
@@ -0,0 +1,15 @@
+{% if objtype == 'property' %}
+:orphan:
+{% endif %}
+
+{{ objname | escape | underline}}
+
+.. rubric:: *module* :mod:`{{ module }}`
+
+.. currentmodule:: {{ module }}
+
+{% if objtype == 'property' %}
+property
+{% endif %}
+
+.. auto{{ objtype }}:: {{ fullname | replace(module + ".", module + "::") }}
diff --git a/documentation/_templates/autosummary/class.rst b/documentation/_templates/autosummary/class.rst
@@ -0,0 +1,37 @@
+{{ objname | escape | underline}}
+
+.. rubric:: *module* :mod:`{{ module }}`
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+{% block methods %}
+{% if methods %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+
+      {% for item in all_methods %}
+         {%- if not item.startswith('_') or item in ['__call__'] %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+
+      {% for item in all_attributes %}
+         {%- if not item.startswith('_') %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+{% endif %}
+{% endblock %}
+
+   {% if methods or attributes %}
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   {% endif %}
diff --git a/documentation/_templates/autosummary/exception.rst b/documentation/_templates/autosummary/exception.rst
@@ -0,0 +1,34 @@
+{{ objname | escape | underline}}
+
+.. rubric:: *module* :mod:`{{ module }}`
+
+.. currentmodule:: {{ module }}
+
+.. autoexception:: {{ objname }}
+   :no-inherited-members:
+
+{% block methods %}
+{% if methods %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+
+      {% for item in all_methods %}
+         {%- if not item.startswith('_') or item in ['__call__'] %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+
+      {% for item in all_attributes %}
+         {%- if not item.startswith('_') %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/documentation/_templates/autosummary/module.rst b/documentation/_templates/autosummary/module.rst
@@ -0,0 +1,73 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+   :exclude-members: {% for item in attributes %}{{ item }}, {% endfor %}{% for item in functions %}{{ item }}, {% endfor %}{% for item in classes %}{{ item }}, {% endfor %}{% for item in exceptions %}{{ item }}, {% endfor %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: autosummary/base.rst
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :nosignatures:
+      :toctree:
+      :template: autosummary/base.rst
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :nosignatures:
+      :toctree:
+      :template: autosummary/class.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :nosignatures:
+      :toctree:
+      :template: autosummary/exception.rst
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+   :template: autosummary/module.rst
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/documentation/acknowledgements.rst b/documentation/acknowledgements.rst
@@ -3,7 +3,7 @@
     \clearpage
 
 Acknowledgements
-======================================
+================
 
 WNTR is developed through a collaboration between U.S. Environmental Protection Agency, Sandia National
 Laboratories, and the open-source community. The U.S. Environmental Protection Agency acknowledges the

diff --git a/documentation/acronyms.rst b/documentation/acronyms.rst
@@ -12,24 +12,46 @@
 Abbreviations
 ======================================
 
-**API**: Application programming interface
+**AML**: algebraic modeling system
 
-**CSV**: Comma-separated values 
+**API**: application programming interface
+
+**CRS**: coordinate reference system
+
+**CSV**: comma-separated values 
+
+**DD**: demand-driven `(DDA now the preferred term)`
+
+**DDA**: demand-driven analysis
 
 **EPA**: Environmental Protection Agency
 
-**GIS**: Geographic information system
+**EPANET**: a water network modeling tool, see :cite:t:`ross00` and :cite:t:`rwts20`
+
+**GIS**: geographic information system
 
 **HDF**: Hierarchical Data Format
 
-**IDE**: Integrated development environment
+**IDE**: integrated development environment
+
+**INP file**: a text input file for EPANET
+
+**I/O**: input and output
 
 **JSON**: JavaScript Object Notation
 
+**PDA**: pressure-driven analysis
+
+**PDD**: pressure dependent demand `(PDA now the preferred term)`
+
+**SCADA**: supervisory control And data acquisition
+
 **SI**: International System of Units
 
 **SQL**: Structured Query Language
 
 **US**: United States
 
+**UTM**: Universal Transverse Mercator
+
 **WNTR**: Water Network Tool for Resilience
diff --git a/documentation/apidoc/wntr.epanet.io.rst b/documentation/apidoc/wntr.epanet.io.rst
diff --git a/documentation/apidoc/wntr.epanet.rst b/documentation/apidoc/wntr.epanet.rst
diff --git a/documentation/apidoc/wntr.epanet.toolkit.rst b/documentation/apidoc/wntr.epanet.toolkit.rst
diff --git a/documentation/apidoc/wntr.epanet.util.rst b/documentation/apidoc/wntr.epanet.util.rst
diff --git a/documentation/apidoc/wntr.gis.geospatial.rst b/documentation/apidoc/wntr.gis.geospatial.rst
diff --git a/documentation/apidoc/wntr.gis.network.rst b/documentation/apidoc/wntr.gis.network.rst
diff --git a/documentation/apidoc/wntr.gis.rst b/documentation/apidoc/wntr.gis.rst
diff --git a/documentation/apidoc/wntr.graphics.color.rst b/documentation/apidoc/wntr.graphics.color.rst
diff --git a/documentation/apidoc/wntr.graphics.curve.rst b/documentation/apidoc/wntr.graphics.curve.rst
diff --git a/documentation/apidoc/wntr.graphics.layer.rst b/documentation/apidoc/wntr.graphics.layer.rst
diff --git a/documentation/apidoc/wntr.graphics.network.rst b/documentation/apidoc/wntr.graphics.network.rst