Dedicated User Documentation (#1095)

krowvin · web-flow · commit 552db0e104ad · 2025-05-08T13:01:14.000-07:00
# Dedicated CDA Documentation


## Notes
* Uses Read the Docs
* ReStructured Text


## Plan

Provides additional information that can be cross referenced through
swagger pages and other places for users to read more on a topic.
Decided the Wiki GitHub pages were not extensible enough.

Will potentially migrate some of the wiki topics into this. 

*Drafting for now to provide awareness but also solicit help more*
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Required
+version: 2
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt
+ 
+
+formats:
+  - pdf
+  - epub
+
+
diff --git a/cwms-data-api/src/main/webapp/templates/HEC.header.html b/cwms-data-api/src/main/webapp/templates/HEC.header.html
@@ -16,6 +16,7 @@
                                     <ul class="top-level-menu">
                                         <li><a href="./swagger-docs">Swagger Docs</a></li>
                                         <li><a href="./swagger-ui.html">Swagger UI</a></li>
+                                        <li id="sphinx-docs" />
                                     </ul>
                                 </div>
                                 <div id="mobile-menu">
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx
+sphinx_rtd_theme
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,37 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = "CWMS Data API"
+copyright = "Public Domain"
+author = "HEC, Various"
+
+# TODO: Sort this out later, what version? Does this get used?
+release = "0.0"
+version = "0.0.0"
+
+# -- General configuration
+
+# TODO: sphinxjs? direct use of API in the docs?
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+templates_path = ["_templates"]
+
+# -- Options for HTML output
+
+html_theme = "sphinx_rtd_theme"
+
+# -- Options for EPUB output
+epub_show_urls = "footnote"
diff --git a/docs/source/data/location-levels.rst b/docs/source/data/location-levels.rst
@@ -0,0 +1,4 @@
+###############
+Location Levels
+###############
+
diff --git a/docs/source/data/timeseries.rst b/docs/source/data/timeseries.rst
@@ -0,0 +1,3 @@
+##########
+TimeSeries
+##########
diff --git a/docs/source/datatypes.rst b/docs/source/datatypes.rst
@@ -0,0 +1,3 @@
+#########
+Datatypes
+#########
diff --git a/docs/source/endpoints/authorization.rst b/docs/source/endpoints/authorization.rst
@@ -0,0 +1,53 @@
+#############
+Authorization
+#############
+
+
+This document provides an overview of the `Authorization API` endpoints used for managing `CWMS Data API` authentication keys.
+
+Endpoints
+---------
+
+*Authentication is required to access these endpoints*
+
+
+* GET `/cwms-data/auth/keys/{key-name}` : Retrieve `CDA` authentication keys by a specific `name`.
+
+
+
+**Request**
+- 
+**Response**
+- **Status**: 200 OK
+- **Body**: Returns the details of the specified authentication key.
+
+#### Retrieve a Key
+
+
+The following table provides an overview of the available endpoints in the Authorization API:
+
++--------------------------------------------+---------------------------------------------+-----------------------------------+
+| **Endpoint**                               | **Description**                             | **Details**                      |
++============================================+=============================================+===================================+
+| `GET /cwms-data/auth/keys/{key-name}`      | Retrieve a specific auth key by `keyName`.  | Returns key details in JSON.     |
++--------------------------------------------+---------------------------------------------+-----------------------------------+
+| `DELETE /cwms-data/auth/keys/{key-name}`   | Delete a specific auth key by `keyName`.    | Returns `204 No Content` status. |
++--------------------------------------------+---------------------------------------------+-----------------------------------+
+| `GET /cwms-data/auth/keys`                 | Retrieve all available auth keys.           | Returns list of keys in JSON.    |
++--------------------------------------------+---------------------------------------------+-----------------------------------+
+| `POST /cwms-data/auth/keys`                | Create or update an auth key.               | Returns created/updated key.     |
++--------------------------------------------+---------------------------------------------+-----------------------------------+
+
+========== ================================= ========================================== ===========
+**Method** **Endpoint**                      **Description**                            **Details**
+========== ================================= ========================================== ===========
+`GET`      `/cwms-data/auth/keys/{key-name}` Retrieve a specific auth key by `keyName`. 
+`DELETE`   `/cwms-data/auth/keys/{key-name}` Delete a specific auth key by `keyName`.
+`GET`      `/cwms-data/auth/keys`            Retrieve all available auth keys.
+`POST`     `/cwms-data/auth/keys`            Create or update an auth key.    
+========== ================================= ========================================== ===========
+
+Notes
+-----
+- Replace `{key-name}` with the name of the key you are targeting.
+- Ensure authentication headers are included if required.
diff --git a/docs/source/endpoints/index.rst b/docs/source/endpoints/index.rst
@@ -0,0 +1,9 @@
+###############
+Endpoints Index
+###############
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Introduction
+   
+   Authorization <./authorization.rst>
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -0,0 +1,24 @@
+.. _faq:
+
+Frequently Asked Questions
+===========================
+
+1. **Question:** What is CWMS Data API?
+   
+**Answer:** CWMS Data API is a web service that provides access to water management data. Review the :ref:`glossary`. for more information.
+
+2. **Question:** How do I get started with CWMS Data API?
+   
+   **Answer:** You can get started by reading the documentation and following the setup instructions provided.
+
+3. **Question:** What kind of data can I access using CWMS Data API?
+   
+   **Answer:** You can access various types of water management data including reservoir levels, inflows, outflows, and more.
+
+4. **Question:** Is there any authentication required to use the API?
+   
+   **Answer:** Yes, you need to obtain an API key to authenticate your requests that require writing, updating, or deleting data, or if the endpoint contains sensitive data (API Keys, etc).
+
+5. **Question:** Where can I find more information?
+   
+   **Answer:** This site contains user information but we also have a `SwaggerUI <https://cwms-data.usace.army.mil/cwms-data>`_ for developers to experiment with the endpoints. 
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
@@ -0,0 +1,137 @@
+.. _glossary:
+
+CDA Glossary
+============
+
+General Terms
+-------------
+**API**:
+    An Application Programming Interface (API) is a set of rules and protocols that allows different software applications to communicate with each other.
+
+**Client**:
+    A client is a computer program or device that requests services or resources from a server.
+
+**Server**:
+    A server is a computer program or device that provides services or resources to clients.
+
+**URL**:
+    A Uniform Resource Locator (URL) is a reference to a web resource that specifies its location on a computer network and the protocol used to access it.
+
+**URI**:
+    A Uniform Resource Identifier (URI) is a string of characters that identifies a resource on the internet.
+
+**Endpoint**:
+    An endpoint is a specific URL or URI that is part of a web service or API.
+
+**Request**:
+    A request is a message sent from a client to a server, typically asking for some action to be performed.
+
+
+CDA Glossary Terms
+------------------
+
+**CWMS**: 
+    The Corps Water Management System (CWMS) is a comprehensive water management system used by the U.S. Army Corps of Engineers.
+
+**Data API**:
+    A Data API is an Application Programming Interface that allows users to access and manipulate data from a database or other data source.
+
+**CDA**:
+    The CWMS Data API (CDA) is an API that provides access to data from the Corps Water Management System.
+
+**Authentication**:
+    Authentication is the process of verifying the identity of a user or system.
+
+**Authorization**:
+    Authorization is the process of granting or denying access to resources based on the identity of the user or system.
+
+**Key**:
+    A key is a unique identifier used for authentication and authorization purposes.
+
+**Base URL**:
+    The base URL is the starting point for a URL or URI, typically indicating the domain or server where the resource is located.
+
+**Client Library**:
+    A client library is a set of pre-written code that simplifies the process of interacting with an API or service.
+
+**Maintainer**:
+    A maintainer is a person or organization responsible for maintaining and updating a software library or project.
+
+**Contributor**:
+    A contributor is a person who contributes code, documentation, or other resources to a software project.
+
+**GitHub**:
+    GitHub is a web-based platform for hosting and collaborating on software development projects using the Git version control system.
+
+
+Hydrologic Terms
+----------------
+
+**Reservoir**: 
+    A reservoir is a large natural or artificial lake used as a source of water supply.
+
+**Hydrology**: 
+    Hydrology is the scientific study of the movement, distribution, and quality of water on Earth and other planets.
+
+**Inflow**: 
+    Inflow refers to the water entering a reservoir or other body of water.
+
+**Outflow**: 
+    Outflow is the water that exits a reservoir or other body of water.
+
+**Flood Control**: 
+    Flood control involves the management of water resources to prevent or reduce the risk of flooding.
+
+**Water Quality**: 
+    Water quality refers to the chemical, physical, and biological characteristics of water, usually in respect to its suitability for a particular purpose.
+
+**Watershed**: 
+    A watershed is an area of land that separates waters flowing to different rivers, basins, or seas.
+
+**Discharge**: 
+    Discharge is the volume of water that flows through a river or stream over a given period of time.
+
+**Sedimentation**: 
+    Sedimentation is the process of settling or being deposited as sediment.
+
+**Evaporation**: 
+    Evaporation is the process by which water changes from a liquid to a gas or vapor.
+
+**Precipitation**: 
+    Precipitation is any form of water - liquid or solid - falling from the sky, including rain, snow, sleet, and hail.
+
+**Runoff**: 
+    Runoff is the part of precipitation that flows over the land surface towards streams, rivers, or other bodies of water.
+
+**Water Conservation**: 
+    Water conservation involves the careful use and management of water resources to ensure their sustainability.
+
+**Drought**: 
+    A drought is a prolonged period of abnormally low rainfall, leading to a shortage of water.
+
+**Hydroelectric Power**: 
+    Hydroelectric power is electricity generated by the energy of moving water.
+
+**Aquifer**: 
+    An aquifer is an underground layer of water-bearing rock or materials from which groundwater can be extracted.
+
+**Riparian**: 
+    Riparian refers to the interface between land and a river or stream.
+
+**Erosion**: 
+    Erosion is the process by which soil and rock are removed from the Earth's surface by wind, water flow, and other natural processes.
+
+**Levee**: 
+    A levee is an embankment built to prevent the overflow of a river.
+
+**Dam**: 
+    A dam is a barrier constructed to hold back water and raise its level, forming a reservoir used to generate electricity or as a water supply.
+
+**Water Table**: 
+    The water table is the level below which the ground is saturated with water.
+
+**Groundwater**: 
+    Groundwater is the water present beneath Earth's surface in soil pore spaces and in the fractures of rock formations.
+
+**Surface Water**: 
+    Surface water is water that collects on the surface of the ground, including rivers, lakes, and reservoirs.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,21 @@
+Welcome to CWMS Data API documentation!
+=======================================
+
+
+* Swagger
+* Wiki
+
+.. Warning::
+   This documentation is a work in progress. It may not be complete or accurate.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Introduction
+   
+   Overview <./introduction/overview.rst>
+   Design <./introduction/design.rst>
+   Endpoints <./endpoints/index.rst>
+   Glossary <./glossary.rst>
+   FAQ <./faq.rst>
+   Client Libraries <./libraries.rst>
diff --git a/docs/source/introduction/design.rst b/docs/source/introduction/design.rst
diff --git a/docs/source/introduction/overview.rst b/docs/source/introduction/overview.rst
diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst
diff --git a/docs/source/libraries/java.rst b/docs/source/libraries/java.rst
diff --git a/docs/source/libraries/javascript.rst b/docs/source/libraries/javascript.rst
diff --git a/docs/source/libraries/jython.rst b/docs/source/libraries/jython.rst
diff --git a/docs/source/libraries/python.rst b/docs/source/libraries/python.rst

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+##########`
	`2`	`+TimeSeries`
	`3`	`+##########`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+#########`
	`2`	`+Datatypes`
	`3`	`+#########`