Set up SDK Reference generation (#269)

This PR configures mkdocs to generate an SDK reference for the Python SDK.

.github/workflows/sdk-reference.yml

@@ -0,0 +1,43 @@
+name: sdk-reference
+
+on:
+  push:
+    branches:
+      - v6.0.0-beta
+  pull_request:
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    environment:
+      name: sdk-reference
+      url: ${{ steps.deploy.outputs.url }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup Nodejs
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Install dependencies and build
+        run: pip install .[docs]
+      - name: Build docs
+        run: python setup.py build-docs
+      - name: Set env BRANCH
+        run: echo "BRANCH=$(echo $GITHUB_REF | cut -d'/' -f 3)" >> $GITHUB_ENV
+      - name: Set env CLOUDFLARE_BRANCH
+        run: |
+          if [[ $BRANCH == 'v6.0.0-beta' && $GITHUB_EVENT_NAME == 'push' ]]; then
+              echo "CLOUDFLARE_BRANCH=main" >> "$GITHUB_ENV"
+          else
+              echo "CLOUDFLARE_BRANCH=$BRANCH" >> "$GITHUB_ENV"
+          fi
+      - name: Publish to Cloudflare Pages
+        uses: cloudflare/pages-action@v1
+        id: deploy
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: nylas-python-sdk-reference
+          directory: site
+          wranglerVersion: "3"
+          branch: ${{ env.CLOUDFLARE_BRANCH }}

.gitignore

@@ -63,5 +63,9 @@ local/
 pip-selfcheck.json
 tests/output
 local.env
-examples/test.py
+nylas/test.py
 .env
+
+# Documentation
+site
+docs

mkdocs.yml

@@ -0,0 +1,23 @@
+site_name: Nylas Python SDK Reference
+theme:
+   name: 'material'
+
+nav:
+  - Getting Started: index.md
+  - Code Reference: reference/
+  - Contributing: contributing.md
+  - License: license.md
+
+# Add plugins
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [ nylas ]
+  - gen-files:
+      scripts:
+        - scripts/generate-docs.py
+  - literate-nav:
+        nav_file: SUMMARY.md

nylas/client.py

@@ -31,6 +31,7 @@ def __init__(
         self.api_uri = api_uri
         self.http_client = HttpClient(self.api_uri, self.api_key, timeout)
 
+    @property
     def auth(self) -> Auth:
         return Auth(self.http_client)
 

nylas/handler/api_resources.py

@@ -1,8 +1,6 @@
 from __future__ import annotations
 
-from nylas.models.delete_response import DeleteResponse
-from nylas.models.list_response import ListResponse
-from nylas.models.response import Response
+from nylas.models.response import Response, ListResponse, DeleteResponse
 from nylas.resources.resource import Resource
 
 

nylas/models/application_details.py

@@ -3,7 +3,7 @@
 
 from dataclasses_json import dataclass_json
 
-from nylas.models.reditect_uri import RedirectUri
+from nylas.models.redirect_uri import RedirectUri
 
 Region = Literal["us", "eu"]
 Environment = Literal["production", "staging"]

nylas/models/response.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from typing import TypeVar, Generic
+from typing import TypeVar, Generic, Optional, List
 
 from dataclasses_json import DataClassJsonMixin, dataclass_json
 
@@ -26,6 +26,53 @@ def from_dict(cls, resp: dict, generic_type):
         )
 
 
+class ListResponse(tuple, Generic[T]):
+    """
+    List response object returned from the Nylas API.
+
+    Attributes:
+        data: The list of requested data objects.
+        request_id: The request ID.
+        next_cursor: The cursor to use to get the next page of data.
+    """
+
+    data: List[T]
+    request_id: str
+    next_cursor: Optional[str] = None
+
+    def __new__(cls, data: List[T], request_id: str, next_cursor: Optional[str] = None):
+        cls = tuple.__new__(cls, (data, request_id, next_cursor))
+        cls.data = data
+        cls.request_id = request_id
+        cls.next_cursor = next_cursor
+        return cls
+
+    @classmethod
+    def from_dict(cls, resp: dict, generic_type):
+        converted_data = []
+        for item in resp["data"]:
+            converted_data.append(generic_type.from_dict(item))
+
+        return cls(
+            data=converted_data,
+            request_id=resp["request_id"],
+            next_cursor=resp.get("next_cursor", None),
+        )
+
+
+@dataclass_json
+@dataclass
+class DeleteResponse:
+    """
+    Delete response object returned from the Nylas API.
+
+    Attributes:
+        request_id: The request ID returned from the API.
+    """
+
+    request_id: str
+
+
 @dataclass_json
 @dataclass
 class RequestIdOnlyResponse:

nylas/resources/calendars.py

@@ -6,10 +6,12 @@
     DestroyableApiResource,
 )
 from nylas.models.availability import GetAvailabilityResponse, GetAvailabilityRequest
-from nylas.models.calendar import Calendar, CreateCalendarRequest, UpdateCalendarRequest
-from nylas.models.delete_response import DeleteResponse
-from nylas.models.list_response import ListResponse
-from nylas.models.response import Response
+from nylas.models.calendars import (
+    Calendar,
+    CreateCalendarRequest,
+    UpdateCalendarRequest,
+)
+from nylas.models.response import Response, ListResponse, DeleteResponse
 
 
 class Calendars(

nylas/resources/events.py

@@ -5,8 +5,7 @@
     UpdatableApiResource,
     DestroyableApiResource,
 )
-from nylas.models.delete_response import DeleteResponse
-from nylas.models.event import (
+from nylas.models.events import (
     Event,
     UpdateEventRequest,
     CreateEventRequest,
@@ -18,8 +17,12 @@
     SendRsvpQueryParams,
     SendRsvpRequest,
 )
-from nylas.models.list_response import ListResponse
-from nylas.models.response import Response, RequestIdOnlyResponse
+from nylas.models.response import (
+    Response,
+    ListResponse,
+    DeleteResponse,
+    RequestIdOnlyResponse,
+)
 
 
 class Events(

nylas/resources/grants.py

@@ -5,15 +5,13 @@
     UpdatableApiResource,
     DestroyableApiResource,
 )
-from nylas.models.delete_response import DeleteResponse
-from nylas.models.grant import (
+from nylas.models.grants import (
     Grant,
     ListGrantsQueryParams,
     CreateGrantRequest,
     UpdateGrantRequest,
 )
-from nylas.models.list_response import ListResponse
-from nylas.models.response import Response
+from nylas.models.response import Response, ListResponse, DeleteResponse
 
 
 class Grants(

nylas/resources/redirect_uris.py

@@ -5,14 +5,12 @@
     UpdatableApiResource,
     DestroyableApiResource,
 )
-from nylas.models.delete_response import DeleteResponse
-from nylas.models.list_response import ListResponse
-from nylas.models.reditect_uri import (
+from nylas.models.redirect_uri import (
     RedirectUri,
     CreateRedirectUriRequest,
     UpdateRedirectUriRequest,
 )
-from nylas.models.response import Response
+from nylas.models.response import Response, ListResponse, DeleteResponse
 
 
 class RedirectUris(

nylas/resources/webhooks.py

@@ -7,8 +7,7 @@
     UpdatableApiResource,
     DestroyableApiResource,
 )
-from nylas.models.list_response import ListResponse
-from nylas.models.response import Response
+from nylas.models.response import Response, ListResponse
 from nylas.models.webhooks import (
     Webhook,
     WebhookWithSecret,