Minor fixes

Problem:
Some incorrect documentation.

Solution:
Fix minor faults in documentation and update sbom
release example code.

Signed-off-by: User Name <user@email.com>

Author: Paul Hewlett

README.rst

@@ -1,3 +1,4 @@
+
 .. _readme:
 
 Jitsuin Archivist Client
@@ -13,16 +14,23 @@ Installation
 
 Use standard python pip utility:
 
-.. code-block:: bash
+.. code:: bash
 
     python3 -m pip install jitsuin-archivist
 
+If your version of python3 is too old an error of this type or similar will be emitted:
+
+.. note:: 
+
+    ERROR: Could not find a version that satisfies the requirement jitsuin-archivist (from versions: none)
+    ERROR: No matching distribution found for jitsuiin-archivist
+
 Example
 =============
 
 One can then use the examples code to create assets (see examples directory):
 
-.. code-block:: python
+.. code:: python
 
     """Create an asset given url to Archivist and user Token.
 
@@ -138,7 +146,7 @@ or json file.
 Python
 ------
 
-.. code-block:: python
+.. code:: python
 
     from logging import getLogger
     from pyaml_env import parse_config
@@ -182,7 +190,7 @@ Command Line
 
 This functionality is also available from the command line:
 
-.. code-block:: shell
+.. code:: shell
 
    $ archivist_runner -h
 
@@ -196,7 +204,7 @@ To invoke this command:
 
 Execute:
 
-.. code-block:: shell
+.. code:: shell
 
    $ archivist_runner \
          -u https://app.rkvst.io \
@@ -225,7 +233,7 @@ asset or event is confirmed before returning.
    'true' which archivist will treat as a boolesn.
 
 
-.. code-block:: yaml
+.. code:: yaml
 
     ---
     # Demonstration of applying a Richness compliance policy to an asset that undergoes
@@ -294,7 +302,7 @@ by using dictionary configuration as described here: https://docs.python.org/3/l
 
 A recommended minimum configuration would be:
 
-.. code-block:: python
+.. code:: python
 
     import logging
 

docs/requirements.txt

@@ -1,18 +1,20 @@
 #
 # this is used for pushing to github pages
 #
-# for development, the correct packages are installed in the builder image.
-#
-# Duplicate of stanza in builder/Dockerfile-builder
+# Duplicate of stanza in ~/requirements-dev.txt.
 # Make changes in both places
-#
-sphinx==3.5.4
-sphinx-rtd-theme==0.5.2
+sphinx~=4.3
+sphinx-rtd-theme~=1.0.0
 
-backoff==1.10.0
-certifi==2020.12.5
-flatten-dict==0.3.0
-iso8601==0.1.13
-requests==2.22.0
-requests-toolbelt==0.9.1
-rfc3339==6.2
+# Duplicate of stanza in ~/requirements.txt.
+# Make changes in both places
+backoff~=1.11
+certifi
+flatten-dict~=0.3
+iso8601~=0.1
+Jinja2~=3.0
+pyaml-env~=1.1
+requests~=2.22
+requests-toolbelt~=0.9
+rfc3339~=6.2
+xmltodict~=0.12.0

docs/runner/events_create.rst

@@ -74,7 +74,7 @@ An example when releasing a software package as an sbom:
         confirm: true
         event_attributes:
           arc_description: ACME Corporation Detector SAAS Released YYYYMMDD.1
-          arc_display_type: sbom release
+          arc_display_type: Software Package Release
         sbom:
           filename: functests/test_resources/sbom/gen1.xml
           content_type: text/xml
@@ -100,10 +100,9 @@ An example when releasing a software package as an sbom attachment:
         confirm: true
         event_attributes:
           arc_description: ACME Corporation Detector SAAS Released YYYYMMDD.1
-          arc_display_type: sbom release
+          arc_display_type: Software Package Release
         attachments:
           - filename: functests/test_resources/sbom/gen1.xml
             content_type: text/xml
             display_name: ACME Generation1 SBOM
-            type: SBOM_RELEASE
-
+            type: Software Package Release

examples/sbom_release.py

@@ -1,3 +1,5 @@
+#!/usr/bin/python3
+
 """
 Test sbom release process
 """
@@ -16,19 +18,20 @@
 
 filterwarnings("ignore", message="Unverified HTTPS request")
 
+ASSET_NAME = "RKVST SaaS Software Package"
+
 
-def sbom_release(arch, release, sbom_filename):  # XXX instead of filename may be URL?
+def sbom_release(arch, release, sbom_filename):
     """
     Test sbom release process
 
-    Because we use create_if_not_exists the software package asset and attachments will persist.
+    Because we use create_if_not_exists the software package asset will persist.
 
     Args:
         release (str): release string of form YYYYMMDD.N
+        sbom_filename (str): name of sbom file
     """
 
-    ASSET_NAME = "RKVST SAAS Software Package"
-
     print(f"##[debug]Creating software package {ASSET_NAME}")
 
     asset, existed = arch.assets.create_if_not_exists(
@@ -45,25 +48,15 @@ def sbom_release(arch, release, sbom_filename):  # XXX instead of filename may b
             "attributes": {
                 "arc_display_name": ASSET_NAME,
                 "arc_display_type": SBOM_PACKAGE,
-                "arc_description": "Software Package for RKVST SAAS",
-                "acme_sbom_license": "www.gnu.org/licenses/gpl.txt",  # XXX
-                "acme_proprietary_secret": "For your eyes only",  # XXX
+                "arc_description": "Software Package for RKVST SaaS",
             },
-            # the attachment should be the RKVST logo? - change accordingly XXX
-            "attachments": [
-                {
-                    "url": (
-                        "https://raw.githubusercontent.com/jitsuin-inc/archivist-python/"
-                        "main/functests/test_resources/telephone.jpg",
-                    ),
-                    "content_type": "image/jpg",
-                },
-            ],
         },
         confirm=True,
     )
-    print("asset", json_dumps(asset, indent=4))
-    print("existed", existed)
+    print("##[debug]Asset:\n", json_dumps(asset, indent=4))
+    print("##[debug]Existed:", existed)
+
+    print("")
 
     # Releasing an SBOM
     event = arch.events.create_from_data(
@@ -72,12 +65,12 @@ def sbom_release(arch, release, sbom_filename):  # XXX instead of filename may b
             "operation": "Record",
             "behaviour": "RecordEvidence",
             "event_attributes": {
-                "arc_description": f"Jitsuin Inc RKVST SAAS Released {release}",
+                "arc_description": f"Jitsuin Inc RKVST SAAS Release {release}",
                 "arc_display_type": SBOM_RELEASE,
             },
             "attachments": [
                 {
-                    "filename": f"{sbom_filename}",  # XXX maybe change to URL?
+                    "filename": f"{sbom_filename}",
                     "content_type": "text/xml",
                     "display_name": f"RKVST {release} SBOM",
                     "type": SBOM_RELEASE,
@@ -86,28 +79,39 @@ def sbom_release(arch, release, sbom_filename):  # XXX instead of filename may b
         },
         confirm=True,
     )
-    print("release", json_dumps(event, indent=4))
-    event = arch.events.list(
-        asset_id=asset["identity"],
-        props={"confirmation_status": "CONFIRMED"},
-        attrs={"arc_display_type": SBOM_RELEASE},
-    )
+    print("##[debug]Release:\n", json_dumps(event, indent=4))
+
+    return (asset, event)
 
 
 def main():
     """
     main entry point
     """
+
+    rkvst_url = getenv("RKVST_URL")
+
     auth = get_auth(
-        auth_token_filename=getenv("TEST_AUTHTOKEN_FILENAME"),
-        client_id=getenv("TEST_CLIENT_ID"),
-        client_secret_filename=getenv("TEST_CLIENT_SECRET_FILENAME"),
+        auth_token_filename=getenv("AUTHTOKEN_FILENAME"),
+        client_id=getenv("CLIENT_ID"),
+        client_secret_filename=getenv("CLIENT_SECRET_FILENAME"),
     )
 
-    arch = Archivist(getenv("TEST_ARCHIVIST"), auth, verify=False, max_time=300)
+    arch = Archivist(rkvst_url, auth, verify=False, max_time=300)
+
+    asset, event = sbom_release(
+        arch, getenv("BUILD_BUILDNUMBER"), getenv("SBOM_FILEPATH")
+    )
+
+    rkvst_path = "archivist/v2"
+
+    asset_url = f"{rkvst_url}/{rkvst_path}/{asset['identity']}"
+    event_url = f"{rkvst_url}/{rkvst_path}/{event['identity']}"
 
-    # XXX: change these accordingly - filename may be a url?
-    sbom_release(arch, "YYYYMMDD.N", "tmp/rkvst_saas_YYYYMMDD.N")
+    print(f"##vso[task.setvariable variable=RKVST_ASSET_URL]{asset_url}")
+    print(f"##vso[task.setvariable variable=RKVST_EVENT_URL]{event_url}")
+    print(f"##[debug]Asset url: {asset_url}")
+    print(f"##[debug]Event url: {event_url}")
 
 
 if __name__ == "__main__":

requirements-dev.txt

@@ -12,5 +12,7 @@ pylint~=2.6
 twine~=3.4
 
 # documentation
+# the file docs/requirements.txt
+# must be kept in sync with this file.
 sphinx~=4.3
 sphinx-rtd-theme~=1.0.0

requirements.txt

@@ -1,3 +1,7 @@
+#
+# for the published wheel - the file docs/requirements.txt
+# must be kept in sync with this file.
+#
 backoff~=1.11
 certifi
 flatten-dict~=0.3