Autodocs (#313)

Automated update the API documentation published to https://aws.github.io/aws-iot-device-sdk-python-v2/

**Issue:**
- Docs weren't updated unless someone remembered to do it manually.
- Manually updating docs whenever you update code pollutes the diff, making it hard to review
- Having HTML docs in `main` branch can cause issues.
   - Bloats size.
   - Generated docs might contain licenses we don't want to be redistributing.

**Description of changes:**
- Docs are kept in `docs` branch now
    - New `docs.yml` Github Workflow updates the `docs` branch whenever the `main` branch changes.
    - New `check-docs` job in `ci.yml` checks pull-requests for anything that would break docs.
    - delete the `docs/` folder in `main` and use `.gitignore` to prevent someone from accidentally resurrecting it.

Author: graebm

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches:
-      - '*'
-      - '!main'
+    branches-ignore:
+      - 'main'
+      - 'docs'
 
 env:
   BUILDER_VERSION: v0.8.28
@@ -45,4 +45,15 @@ jobs:
         chmod a+x builder
         ./builder build -p ${{ env.PACKAGE_NAME }}
 
-
+  # check that docs can still build
+  check-docs:
+    runs-on: ubuntu-20.04 # latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: true
+      - name: Check docs
+        run: |
+          python3 -m pip install sphinx
+          python3 -m pip install --verbose .
+          ./make-docs.py

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+# Update the API documentation whenever the `main` branch changes.
+# This documentation lives in its own `docs` branch.
+name: docs
+
+on:
+  push:
+    branches:
+      - 'main'
+
+jobs:
+  update-docs-branch:
+    runs-on: ubuntu-20.04 # latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Update docs branch
+        run: |
+          python3 -m pip install sphinx
+          python3 -m pip install --verbose .
+          ./make-docs.py
+
+      - name: Commit
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git add --force docs/
+          git commit --message="update docs"
+
+      - name: Push to docs branch
+        uses: ad-m/[email protected]
+        with:
+          github_token: ${{ github.token }}
+          branch: docs
+          # Force push so that `docs` branch always looks like `main`,
+          # but with 1 additional "update docs" commit.
+          # This seems simpler than trying to cleanly merge `main` into
+          # `docs` each time.
+          force: true

.gitignore

@@ -3,3 +3,6 @@ docs/.doctrees/
 __pycache__/
 *.egg-info
 build/*
+
+# docs are updated automatically by .github/workflows/docs.yml
+docs/

awsiot/greengrasscoreipc/__init__.py

@@ -32,7 +32,7 @@ def connect(*,
             environment variable AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT
         authtoken: Authentication token, defaults to environment variable SVCUID
         lifecycle_handler: Handler for events over the course of this
-            network connection. See :class:`LifecycleHandler` for more info.
+            network connection. See :class:`awsiot.eventstreamrpc.LifecycleHandler` for more info.
             Handler methods will only be invoked if the connect attempt
             succeeds.
         timeout: The number of seconds to wait for establishing the connection.

awsiot/mqtt_connection_builder.py

@@ -292,7 +292,7 @@ def mtls_with_pkcs11(*,
             The certificate must be PEM-formatted. The certificate may be
             specified by other means instead (ex: `cert_bytes`)
 
-        cert_bytes (Optional[bytes-like object]):
+        cert_bytes (Optional[Union[str, bytes, bytearray]]):
             Use this X.509 certificate (contents in memory).
             The certificate must be PEM-formatted. The certificate may be
             specified by other means instead (ex: `cert_filepath`)