Merge pull request #78 from davidraker/docs

Docs

.github/workflows/run-tests.yml

@@ -33,8 +33,8 @@ jobs:
   run-tests:
     strategy:
       matrix:
-        os: ["ubuntu-20.04", "ubuntu-22.04"]
-        python: ["3.8", "3.9", "3.10"]
+        os: [ubuntu-22.04]
+        python: ['3.10', '3.11']
 
     runs-on: ${{ matrix.os }}
 

README.md

@@ -4,12 +4,23 @@ and utility pages for administration and certificate management.
 This library cannot be installed as a VOLTTRON agent is.
 Rather, it must be installed as a python package.
 
+![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)
+![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)
 [![Run Pytests](https://github.com/eclipse-volttron/volttron-lib-web/actions/workflows/run-tests.yml/badge.svg)](https://github.com/eclipse-volttron/volttron-lib-web/actions/workflows/run-tests.yml)
 [![pypi version](https://img.shields.io/pypi/v/volttron-lib-web.svg)](https://pypi.org/project/volttron-lib-web/)
 
-## Requirements
-* python >=3.8
+# Requires
+
+* python >= 3.10
 * volttron >= 10.0
+* jinja2-cli >= 0.7.0
+* passlib >= 1.7.4
+* PyJWT == 1.7.1
+* treelib >= 1.6.1
+* werkzeug >= 2.1.2
+* ws4py = >= 0.5.1
+* requests >= 2.28.1
+* argon2-cffi >= 21.3.0
 
 ## Installation
 This library can be installed using pip:
@@ -55,7 +66,7 @@ and web_secret_key should not be included. If SSL is not desired,
 provide a web_secret_key instead and remove the lines for the web_ssl_cert
 and web_ssl_key. Any string can be used for the web_secret_key.
 
-Full VOLTTRON documentation is available at [VOLTTRON Readthedocs](https://volttron.readthedocs.io)
+Full VOLTTRON documentation is available at [VOLTTRON Readthedocs](https://eclipse-volttron.readthedocs.io/)
 
 
 ## Use
@@ -66,7 +77,7 @@ configuration shown above). This will create a file called web-users.json in the
 
 Additionally, the web service provides a RESTful API which can be used by other applications. Full documentation for
 the API is available on 
-[Readthedocs](https://volttron.readthedocs.io/en/main/platform-features/web-api/introduction.html).
+[Readthedocs](https://eclipse-volttron.readthedocs.io/en/latest/external-docs/volttron-lib-web/docs/source/index.html).
 
 Note that it is necessary for most API endpoints to have previously created a username and password for authentication
 by visiting the /admin page or by manually copying or creating a web-users.json file. Authentication can then be
@@ -92,7 +103,7 @@ print(platforms.json())
 
 Please see the following for contributing guidelines [contributing](https://github.com/eclipse-volttron/volttron-core/blob/develop/CONTRIBUTING.md).
 
-Please see the following helpful guide about [developing modular VOLTTRON agents](https://github.com/eclipse-volttron/volttron-core/blob/develop/DEVELOPING_ON_MODULAR.md)
+Please see the following helpful guide about [developing modular VOLTTRON agents](https://eclipse-volttron.readthedocs.io/en/latest/developing-volttron/developing-agents/agent-development.html)
 
 # Disclaimer Notice
 

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)

docs/source/authentication-endpoints.rst

@@ -0,0 +1,113 @@
+.. _Authentication-Endpoints:
+
+========================
+Authentication EndPoints
+========================
+
+The VOLTTRON Web API requires the use of bearer tokens to access resources.  These tokens
+are JSON Web Tokens (JWT) and are provided by the two ``/authenticate`` endpoints (``POST``
+and ``PUT``).  Two classes of token are provided to the user:
+
+- Refresh Tokens:
+    Refresh tokens are long-lived, and used can be used to obtain a new short-lived access
+    token. Refresh tokens are obtained by providing a valid username and password to the
+    ``POST /authenticate`` endpoint. The refresh token SHOULD be kept secure on the
+    client side, and SHOULD NOT be provided to API call other than to
+    ``PUT /authenticate``.
+
+- Access Tokens:
+    An access token are short-lived tokens required to obtain resources or services provided
+    by other API endpoints. The access token is obtained using the ``PUT /authenticate``
+    endpoint. For convenience, an inital access token is provided by the
+    ``POST /authenticate`` endpoint as well, but as use the ``POST`` method requires
+    sending credentials to the server, this should only be used on the first call, with
+    ``PUT`` being used thereafter to obtain new access tokens until the refresh token has
+    also expired.
+
+.. note:: Authentication begins by obtaining a JWT bearer refresh token from the
+    ``POST /authenticate`` endpoint. An initial access token is provided by this endpoint
+    as well. Subsequent access tokens are then obtained by providing the refresh token to the
+    ``PUT /authenticate`` endpoint without resending of credentials.
+
+----------------------------------------------------------------------------
+
+POST /authenticate
+==================
+
+Provide authentication credentials to receive refresh token.
+
+The user provides a username and password in the request body. If authentication succeeds,
+the endpoint will returna a JWT bearer refresh token with user’s claims. An initial access
+token is also returned. The refresh token can then be provided to ``PUT /authenticate``
+to obtain new short-lived access tokens, as needed, without sending the username and
+password again until the refresh token expires.
+
+Request:
+--------
+- Content Type: ``application/json``
+- Body:
+
+  .. code-block:: javascript
+
+        {
+            "username": "<username>",
+            "password": "<password>"
+        }
+
+Response:
+---------
+
+* **With valid username and password:** ``200 OK``
+    - Content Type: ``application/json``
+    - Body:
+
+      .. code-block:: javascript
+
+            {
+                "refresh_token": "<jwt_refresh_token>",
+                "access_token": "<jwt_access_token>"
+            }
+
+* **With invalid username and password:** ``401 Unauthorized``
+
+--------------
+
+PUT /authenticate
+=================
+
+Renew access token.
+
+The user provides a valid refresh token (provided by ``POST /authenticate``) in the
+Authorization header to obtain a fresh access token. A current access token MAY also
+be provided, as needed, in the request body to keep open any existing subscriptions.
+All subsequent requests to any endpoint should include the new token, and the old
+access token should be discarded.
+
+Request:
+--------
+
+- Content Type: ``application/json``
+- Authorization: ``BEARER <jwt_refresh_token>``
+- Body (optional):
+
+  .. code-block:: javascript
+
+        {
+          "current_access_token": "<jwt_access_token>"
+        }
+
+Response:
+---------
+
+* **With valid refresh token:** ``200 OK``
+    - Content Type: ``application/json``
+    - Body:
+
+      .. code-block:: javascript
+
+            {
+                "access_token": "<new_jwt_access_token>"
+            }
+
+* **With invalid or mismatched username, password, or token:**
+   ``401 Unauthorized``

docs/source/conf.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*- {{{
+# ===----------------------------------------------------------------------===
+#
+#                 Installable Component of Eclipse VOLTTRON
+#
+# ===----------------------------------------------------------------------===
+#
+# Copyright 2022 Battelle Memorial Institute
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy
+# of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# ===----------------------------------------------------------------------===
+# }}}
+
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'VOLTTRON Web Service'
+copyright = '2022, Pacific Northwest National Lab'
+author = 'Pacific Northwest National Lab'
+
+release = '0.2'
+version = '0.2.0-rc'
+
+# -- General configuration
+
+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'