update docs (#367)

* update docs * <bot> update requirements-docs.txt * <bot> update requirements-tests.txt * <bot> update requirements.txt * new moto needs [s3] * <bot> update requirements-tests.txt * convert to moto 5 syntax * make sure we use moto >= 5 * bump to py 3.10 for docs build * <bot> update requirements-tests.txt * python version needs to be a string * <bot> update requirements-docs.txt * <bot> update requirements-tests.txt * <bot> update requirements.txt * fix import --------- Co-authored-by: github-actions <[email protected]>
WIPACrepo · Jan 30, 2024 · ab611f0 · ab611f0
1 parent 2d6a41e
commit ab611f0
Show file tree

Hide file tree

Showing 18 changed files with 155 additions and 138 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.9
-      uses: actions/setup-python@v2
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: "3.10"
     - name: Install deps
       run: |
         python -m pip install --upgrade pip

diff --git a/docs/guide/login.rst b/docs/guide/login.rst
@@ -3,31 +3,4 @@ Login
 
 Users can log in to IceProd like any other web application.
 
-Authentication is handled by an external plugin
-such as `LDAP`_.
-
-.. _LDAP: https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol
-
-.. note::
-   :class: icecube
-
-   LDAP authentication is set up for IceCube users.
-
-
-Two Factor Authentication
--------------------------
-
-Certain pages and actions require additional authentication.  When a new
-account is registered with IceProd, two-factor authentication must be
-set up.
-
-IceProd uses time-based one-time passwords (`RFC 6238`_), as used by
-Google, GitHub, and others.  Using a phone app such as Google Authenticator,
-a barcode image specific to each user can be scanned and registered.  The
-app will then generate short codes valid for 30 seconds each.
-
-Example barcode image:
-
-.. image:: ../static/2fa_barcode.png
-
-.. _RFC 6238: https://tools.ietf.org/html/rfc6238
+Authentication is handled by IceCube SSO.
diff --git a/docs/guide/restapi.rst b/docs/guide/restapi.rst
@@ -14,16 +14,58 @@ Authentication
 To view datasets, call actions on datasets, or submit new datasets,
 authentication with a token is required.
 
-An authentication token can be obtained within the account settings
-in the website.  This can be added to requests as the `Authorization` header.
+An authentication token can be obtained using the python package
+`wipac-rest-tools`. For example::
+
+    python3 -m venv venv
+    . venv/bin/activate
+    pip install wipac-rest-tools
+    curl -o get_token.py https://raw.githubusercontent.com/WIPACrepo/rest-tools/master/examples/get_device_credentials_token.py
+    python get_device_credentials_token.py iceprod-public
+
+The access token will be valid for 1 hour.
+
+This can be added to requests as the `Authorization` header.
 As an example, here is a query to get the list of all datasets::
 
     curl -XGET -H 'Authorization: bearer XXXXXXXX-your-token-here-XXXXX' https://iceprod2-api.icecube.wisc.edu/datasets
 
 .. danger::
 
-   Anyone with the authentication token is basically you.  It is valid 
-   for any action that does not require :ref:`Two Factor Authentication`.
-   Be careful with the token!
+   Anyone with the authentication token is basically you. Be careful with the token!
+
+
+Scripting
+^^^^^^^^^
+
+When writing a python script, you can use our rest client to automatically
+manage tokens for you. Just install `wipac-rest-tools` as shown above.
+There are also sync and async code options:
+
+Sync::
+
+    from rest_tools.client import SavedDeviceGrantAuth
+    api = SavedDeviceGrantAuth(
+        address='https://api.iceprod.wisc.edu',
+        token_url='https://keycloak.icecube.wisc.edu/auth/realms/IceCube',
+        filename='.iceprod-auth',
+        client_id'iceprod-public'
+    )
+    # get a list of datasets
+    result = api.request_seq('GET', '/datasets', {})
+    for dataset, metadata in result.items():
+        # do something with the dataset
 
+Async::
 
+    from rest_tools.client import SavedDeviceGrantAuth
+    api = SavedDeviceGrantAuth(
+        address='https://api.iceprod.wisc.edu',
+        token_url='https://keycloak.icecube.wisc.edu/auth/realms/IceCube',
+        filename='.iceprod-auth',
+        client_id'iceprod-public'
+    )
+    # get a list of datasets
+    result = await api.request('GET', '/datasets', {})
+    for dataset, metadata in result.items():
+        # do something with the dataset
diff --git a/docs/server/rest_api/auth.rst b/docs/server/rest_api/auth.rst
@@ -1,4 +1,4 @@
 REST API - Auth
 ===============
 
-.. automodule:: iceprod.server.rest.auth
+.. automodule:: iceprod.rest.handlers.auth
diff --git a/docs/server/rest_api/config.rst b/docs/server/rest_api/config.rst
@@ -1,4 +1,4 @@
 REST API - Config
 =================
 
-.. automodule:: iceprod.server.rest.config
+.. automodule:: iceprod.rest.handlers.config
diff --git a/docs/server/rest_api/datasets.rst b/docs/server/rest_api/datasets.rst
@@ -1,4 +1,4 @@
 REST API - Datasets
 ===================
 
-.. automodule:: iceprod.server.rest.datasets
+.. automodule:: iceprod.rest.handlers.datasets
diff --git a/docs/server/rest_api/grids.rst b/docs/server/rest_api/grids.rst
@@ -1,4 +1,4 @@
 REST API - Grids
 ================
 
-.. automodule:: iceprod.server.rest.grids
+.. automodule:: iceprod.rest.handlers.grids
diff --git a/docs/server/rest_api/jobs.rst b/docs/server/rest_api/jobs.rst
@@ -1,4 +1,4 @@
 REST API - Jobs
 ===============
 
-.. automodule:: iceprod.server.rest.jobs
+.. automodule:: iceprod.rest.handlers.jobs
diff --git a/docs/server/rest_api/logs.rst b/docs/server/rest_api/logs.rst
@@ -1,4 +1,4 @@
 REST API - Logs
 ===============
 
-.. automodule:: iceprod.server.rest.logs
+.. automodule:: iceprod.rest.handlers.logs
diff --git a/docs/server/rest_api/pilots.rst b/docs/server/rest_api/pilots.rst
@@ -1,4 +1,4 @@
 REST API - Pilots
 =================
 
-.. automodule:: iceprod.server.rest.pilots
+.. automodule:: iceprod.rest.handlers.pilots
diff --git a/docs/server/rest_api/task_stats.rst b/docs/server/rest_api/task_stats.rst
@@ -1,4 +1,4 @@
 REST API - Task Stats
 =====================
 
-.. automodule:: iceprod.server.rest.task_stats
+.. automodule:: iceprod.rest.handlers.task_stats
diff --git a/docs/server/rest_api/tasks.rst b/docs/server/rest_api/tasks.rst
@@ -1,4 +1,4 @@
 REST API - Tasks
 ================
 
-.. automodule:: iceprod.server.rest.tasks
+.. automodule:: iceprod.rest.handlers.tasks
diff --git a/requirements-docs.txt b/requirements-docs.txt
@@ -4,17 +4,17 @@
 #
 #    pip-compile --extra=docs --output-file=requirements-docs.txt
 #
-alabaster==0.7.13
+alabaster==0.7.16
     # via sphinx
-anyio==4.0.0
+anyio==4.2.0
     # via httpx
 asyncache==0.3.1
     # via iceprod (setup.py)
-babel==2.13.1
+babel==2.14.0
     # via sphinx
-boto3==1.28.81
+boto3==1.34.31
     # via iceprod (setup.py)
-botocore==1.31.81
+botocore==1.34.31
     # via
     #   boto3
     #   s3transfer
@@ -23,7 +23,7 @@ cachetools==5.3.2
     #   asyncache
     #   iceprod (setup.py)
     #   wipac-rest-tools
-certifi==2023.7.22
+certifi==2023.11.17
     # via
     #   httpcore
     #   httpx
@@ -33,61 +33,61 @@ cffi==1.16.0
     # via cryptography
 charset-normalizer==3.3.2
     # via requests
-cryptography==41.0.5
+cryptography==42.0.2
     # via
     #   iceprod (setup.py)
     #   pyjwt
     #   pyopenssl
-dnspython==2.4.2
+dnspython==2.5.0
     # via pymongo
 docutils==0.20.1
     # via sphinx
-exceptiongroup==1.1.3
+exceptiongroup==1.2.0
     # via anyio
 h11==0.14.0
     # via httpcore
-httpcore==1.0.1
+httpcore==1.0.2
     # via httpx
-httpx==0.25.1
+httpx==0.26.0
     # via iceprod (setup.py)
-idna==3.4
+idna==3.6
     # via
     #   anyio
     #   httpx
     #   requests
 imagesize==1.4.1
     # via sphinx
-jinja2==3.1.2
+jinja2==3.1.3
     # via sphinx
 jmespath==1.0.1
     # via
     #   boto3
     #   botocore
 ldap3==2.9.1
     # via iceprod (setup.py)
-markupsafe==2.1.3
+markupsafe==2.1.4
     # via jinja2
-motor==3.3.1
+motor==3.3.2
     # via iceprod (setup.py)
 packaging==23.2
     # via sphinx
-psutil==5.9.6
+psutil==5.9.8
     # via iceprod (setup.py)
-pyasn1==0.5.0
+pyasn1==0.5.1
     # via ldap3
 pycparser==2.21
     # via cffi
-pygments==2.16.1
+pygments==2.17.2
     # via sphinx
 pyjwt[crypto]==2.8.0
     # via
     #   pyjwt
     #   wipac-rest-tools
-pymongo==4.6.0
+pymongo==4.6.1
     # via
     #   iceprod (setup.py)
     #   motor
-pyopenssl==23.3.0
+pyopenssl==24.0.0
     # via iceprod (setup.py)
 pypng==0.20220715.0
     # via qrcode
@@ -113,7 +113,7 @@ requests-futures==1.0.1
     #   wipac-rest-tools
 requests-toolbelt==1.0.0
     # via iceprod (setup.py)
-s3transfer==0.7.0
+s3transfer==0.10.0
     # via boto3
 setproctitle==1.3.3
     # via iceprod (setup.py)
@@ -126,43 +126,38 @@ sniffio==1.3.0
 snowballstemmer==2.2.0
     # via sphinx
 sphinx==7.2.6
-    # via
-    #   iceprod (setup.py)
-    #   sphinxcontrib-applehelp
-    #   sphinxcontrib-devhelp
-    #   sphinxcontrib-htmlhelp
-    #   sphinxcontrib-qthelp
-    #   sphinxcontrib-serializinghtml
-sphinxcontrib-applehelp==1.0.7
+    # via iceprod (setup.py)
+sphinxcontrib-applehelp==1.0.8
     # via sphinx
-sphinxcontrib-devhelp==1.0.5
+sphinxcontrib-devhelp==1.0.6
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.4
+sphinxcontrib-htmlhelp==2.0.5
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.6
+sphinxcontrib-qthelp==1.0.7
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.9
+sphinxcontrib-serializinghtml==1.1.10
     # via sphinx
 statsd==4.0.1
     # via iceprod (setup.py)
-tornado==6.3.3
+tornado==6.4
     # via
     #   iceprod (setup.py)
     #   wipac-rest-tools
-typing-extensions==4.8.0
+typing-extensions==4.9.0
     # via
+    #   anyio
     #   qrcode
     #   wipac-dev-tools
-unidecode==1.3.7
+unidecode==1.3.8
     # via iceprod (setup.py)
 urllib3==2.0.7
     # via
     #   botocore
     #   requests
     #   wipac-rest-tools
-wipac-dev-tools==1.7.1
+wipac-dev-tools==1.8.2
     # via
     #   iceprod (setup.py)
     #   wipac-rest-tools