Documentation is unavailable on the internet

Problem:
Documentation is auto-generated but is unavailable on the internet.

Solution:
Add action to publishing step that pushes the docs to a gh-pages branch.
On release the docs are published.

Signed-off-by: Paul Hewlett <phewlett76@gmail.com>

Author: eccles

.github/workflows/python-docs.yml

@@ -0,0 +1,33 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+# only used for testing publication step...
+#name: Test docs publishing
+#
+#on: push
+#
+#jobs:
+#  deploy:
+#
+#    runs-on: ubuntu-latest
+#
+#    steps:
+#    - uses: actions/checkout@v2
+#    - name: Set up Python
+#      uses: actions/setup-python@v2
+#      with:
+#        python-version: '3.x'
+#    - name: Install dependencies
+#      run: |
+#        python -m pip install --upgrade pip
+#        pip install setuptools wheel
+#        ./scripts/version.sh
+#    - name: Build docs
+#      uses: ammaraskar/sphinx-action@master
+#      with:
+#        docs-folder: "docs/"
+#    - name: Publish docs
+#      uses: peaceiris/actions-gh-pages@v3
+#      with:
+#        github_token: ${{ secrets.GITHUB_TOKEN }}
+#        publish_dir: "./docs/_build/html"

.github/workflows/python-publish.yml

@@ -30,3 +30,12 @@ jobs:
         ./scripts/version.sh
         python setup.py sdist bdist_wheel
         twine upload dist/*
+    - name: Build docs
+      uses: ammaraskar/sphinx-action@master
+      with:
+        docs-folder: "docs/"
+    - name: Publish docs
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: "./docs/_build/html"

README.md DEVELOPMENT.mdREADME.md renamed to DEVELOPMENT.md

@@ -1,106 +1,3 @@
-# Jitsuin Archivist Client
-
-The standard Jitsuin Archivist python client.
-
-Please note that the canonical API for Jitsuin Archivist is always the REST API
-documented at https://docs.jitsuin.com
-
-# Installation
-
-Use standard python pip utility:
-
-```bash
-python3 -m pip install jitsuin-archivist
-```
-
-One can then use the examples code to create assets (see examples directory):
-
-```python
-from archivist.archivist import Archivist
-from archivist.errors import ArchivistError
-
-# Oauth2 token that grants access
-with open(".auth_token", mode='r') as tokenfile:
-    authtoken = tokenfile.read().strip()
-
-# Initialize connection to Archivist - the URL for production will be different to this URL
-arch = Archivist(
-    "https://rkvst.poc.jitsuin.io",
-    auth=authtoken,
-)
-
-# Create a new asset
-attrs = {
-    "arc_display_name": "display_name",  # Asset's display name in the user interface
-    "arc_description": "display_description",  # Asset's description in the user interface
-    "arc_display_type": "desplay_type",  # Arc_display_type is a free text field
-                                         # allowing the creator of
-                                         # an asset to specify the asset
-                                         # type or class. Be careful when setting this:
-                                         # assets are grouped by type and
-                                         # sharing policies can be
-                                         # configured to share assets based on
-                                         # their arc_display_type.
-                                         # So a mistake here can result in asset data being
-                                         # under- or over-shared.
-        "some_custom_attribute": "value"  # You can add any custom value as long as
-                                      # it does not start with arc_
-}
-behaviours = ["Attachments", "RecordEvidence"]
-
-# The first argument is the behaviours of the asset
-# The second argument is the attributes of the asset
-# The third argument is wait for confirmation:
-#   If @confirm@ is True then this function will not
-#   return until the asset is confirmed on the blockchain and ready
-#   to accept events (or an error occurs)
-#   After an asset is submitted to the blockchain (submitted),
-#   it will be in the "Pending" status.
-#   Once it is added to the blockchain, the status will be changed to "Confirmed"
-try:
-    asset = arch.assets.create(behaviours, attrs=attrs, confirm=True)
-except Archivisterror as ex:
-    print("error", ex)
-else:
-    print("asset", asset)
-
-```
-
-## Logging
-
-Follows the Django model as described here: https://docs.djangoproject.com/en/3.2/topics/logging/
-
-The base logger for this pacakage is rooted at "archivist" with subloggers for each endpoint:
-
-- "archivist.archivist"
-- "archivist.assets"
-- ...
-
-etc. etc.
-
-Logging is configured by either defining a root logger with suitable handlers, formatters etc. or
-by using dictionary configuration as described here: https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
-
-A recommended minimum configuration would be:
-
-```python
-import logging
-
-logging.dictConfig({
-    "version": 1,
-    "disable_existing_loggers": False,
-    "handlers": {
-        "console": {
-            "class": "logging.StreamHandler",
-        },
-    },
-    "root": {
-        "handlers": ["console"],
-        "level": "INFO",
-    },
-})
-```
-
 # Development
 
 ## Pre-requisites
@@ -221,7 +118,7 @@ they be run in a production environment.
 Set 2 environment variables and execute:
 
 ```bash
-export TEST_ARCHIVIST="https://rkvst.poc.jitsuin.io"
+export TEST_ARCHIVIST="https://app.rkvst.io"
 export TEST_AUTHTOKEN_FILENAME=credentials/authtoken
 task functests
 ```

README.rst

@@ -0,0 +1,114 @@
+.. _readme:
+
+Jitsuin Archivist Client
+=========================
+
+The standard Jitsuin Archivist python client.
+
+Please note that the canonical API for Jitsuin Archivist is always the REST API
+documented at https://docs.rkvst.com
+
+Installation
+=============
+
+Use standard python pip utility:
+
+.. code-block:: bash
+
+    python3 -m pip install jitsuin-archivist
+
+Example
+=============
+
+One can then use the examples code to create assets (see examples directory):
+
+.. code-block:: python
+    
+    from archivist.archivist import Archivist
+    from archivist.errors import ArchivistError
+    
+    # Oauth2 token that grants access
+    with open(".auth_token", mode='r') as tokenfile:
+        authtoken = tokenfile.read().strip()
+    
+    # Initialize connection to Archivist - the URL for production will be different to this URL
+    arch = Archivist(
+        "https://app.rkvst.io",
+        auth=authtoken,
+    )
+    
+    # Create a new asset
+    attrs = {
+        "arc_display_name": "display_name",  # Asset's display name in the user interface
+        "arc_description": "display_description",  # Asset's description in the user interface
+        "arc_display_type": "desplay_type",  # Arc_display_type is a free text field
+                                             # allowing the creator of
+                                             # an asset to specify the asset
+                                             # type or class. Be careful when setting this:
+                                             # assets are grouped by type and
+                                             # sharing policies can be
+                                             # configured to share assets based on
+                                             # their arc_display_type.
+                                             # So a mistake here can result in asset data being
+                                             # under- or over-shared.
+            "some_custom_attribute": "value"  # You can add any custom value as long as
+                                          # it does not start with arc_
+    }
+    behaviours = ["Attachments", "RecordEvidence"]
+    
+    # The first argument is the behaviours of the asset
+    # The second argument is the attributes of the asset
+    # The third argument is wait for confirmation:
+    #   If @confirm@ is True then this function will not
+    #   return until the asset is confirmed on the blockchain and ready
+    #   to accept events (or an error occurs)
+    #   After an asset is submitted to the blockchain (submitted),
+    #   it will be in the "Pending" status.
+    #   Once it is added to the blockchain, the status will be changed to "Confirmed"
+    try:
+        asset = arch.assets.create(behaviours, attrs=attrs, confirm=True)
+    except Archivisterror as ex:
+        print("error", ex)
+    else:
+        print("asset", asset)
+    
+
+Logging
+========
+
+Follows the Django model as described here: https://docs.djangoproject.com/en/3.2/topics/logging/
+
+The base logger for this package is rooted at "archivist" with subloggers for each endpoint:
+
+.. note::
+    archivist.archivist
+        sublogger for archivist submodule
+
+    archivist.assets
+        sublogger for assets submodule
+
+and for other endpoints.
+
+Logging is configured by either defining a root logger with suitable handlers, formatters etc. or
+by using dictionary configuration as described here: https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
+
+A recommended minimum configuration would be:
+
+.. code-block:: python
+    
+    import logging
+    
+    logging.dictConfig({
+        "version": 1,
+        "disable_existing_loggers": False,
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+            },
+        },
+        "root": {
+            "handlers": ["console"],
+            "level": "INFO",
+        },
+    })
+

Taskfile.yml

@@ -47,7 +47,7 @@ tasks:
     desc: Create sphinx documentation
     deps: [about]
     cmds:
-      - ./scripts/builder.sh /bin/bash -c "cd docs && make html"
+      - ./scripts/builder.sh /bin/bash -c "cd docs && make clean && make html"
 
   format:
     desc: Format code using black

archivist/access_policies.py

@@ -14,7 +14,7 @@
 
       # Initialize connection to Archivist
       arch = Archivist(
-          "https://rkvst.poc.jitsuin.io",
+          "https://app.rkvst.io",
           auth=authtoken,
       )
       access_policy = arch.access_policies.create(...)

archivist/archivist.py

@@ -11,7 +11,7 @@
    IAM subjects and IAM access policies.
 
    Instantiation of this class encapsulates the URL and authentication
-   parameters:
+   parameters (the max_time paramater is optional):
 
    .. code-block:: python
 
@@ -20,8 +20,9 @@
 
       # Initialize connection to Archivist
       arch = Archivist(
-          "https://rkvst.poc.jitsuin.io",
+          "https://app.rkvst.io",
           auth=authtoken,
+          max_time=1200,
       )
 
     The arch variable now has additional endpoints assets,events,locations,
@@ -415,8 +416,13 @@ def __list(self, path, args, *, headers=None) -> Response:
 
     def last_response(self, *, responses: int = 1) -> List[Response]:
         """Returns the requested number of response objects from the response ring buffer
-        args:
+
+        Args:
             responses (int): Number of responses to be returned in a list
+
+        Returns:
+            list of responses.
+
         """
 
         return list(self._response_ring_buffer)[:responses]

archivist/assets.py

@@ -14,7 +14,7 @@
 
       # Initialize connection to Archivist
       arch = Archivist(
-          "https://rkvst.poc.jitsuin.io",
+          "https://app.rkvst.io",
           auth=authtoken,
       )
       asset = arch.assets.create(...)

archivist/attachments.py

@@ -14,7 +14,7 @@
 
       # Initialize connection to Archivist
       arch = Archivist(
-          "https://rkvst.poc.jitsuin.io",
+          "https://app.rkvst.io",
           auth=authtoken,
       )
       with open("something.jpg") as fd:

archivist/events.py

@@ -14,7 +14,7 @@
 
       # Initialize connection to Archivist
       arch = Archivist(
-          "https://rkvst.poc.jitsuin.io",
+          "https://app.rkvst.io",
           auth=authtoken,
       )
       asset = arch.assets.create(...)