feat: create documentation to be published in ScribeLabs/documentation repo

.github/workflows/update-doc.yml

@@ -0,0 +1,36 @@
+name: Update docs
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  create-files:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create md files
+      run: sphinx-build -M markdown ./docs_source ./docs
+
+  update-docs:
+    runs-on: ubuntu-latest
+    needs: create-files
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Update docs website
+        uses: car-on-sale/[email protected]
+        env:
+          API_TOKEN_GITHUB: ${{ secrets.WEBSITE_GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.WEBSITE_GITHUB_TOKEN }}
+        with:
+          source_folder: 'docs/markdown'
+          destination_repo: 'ScribeLabsAI/documentation'
+          destination_folder: 'docs/SDK/auth-python'
+          destination_base_branch: 'master'
+          destination_head_branch: 'auth-python-update'
+          commit_msg: 'Update Auth Python doc'
+          pr_title: 'Update Auth Python doc'
+          pull_request_reviewers: 'EHadoux'
+          user_email: '[email protected]'
+          user_name: 'ailinvenerus'

docs_source/conf.py

@@ -6,23 +6,27 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'Scribe Auth'
-copyright = '2022, Scribe Labs Limited'
-author = 'Ailin Venerus'
-release = '1.0.2'
+project = "Scribe Auth"
+copyright = "2022, Scribe Labs Limited"
+author = "Ailin Venerus"
+release = "1.0.2"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx_markdown_builder",
+]
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 exclude_patterns = []
 
-
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
-html_static_path = ['_static']
+html_theme = "alabaster"
+html_static_path = ["_static"]
+
+source_dir = "./scribeauth"

docs_source/reference.rst

@@ -1,7 +1,6 @@
 Methods Reference
 =================
 
-.. currentmodule:: scribeauth
-.. autoclass:: ScribeAuth
-    :members:
-    :special-members: __init__
+.. autoclass:: scribeauth.ScribeAuth
+   :members:
+   :special-members: __init__

scribeauth/scribeauth.py

@@ -88,16 +88,13 @@ class ScribeAuth:
     def __init__(self, param: PoolConfiguration):
         """Constructs an authorisation client.
 
-        Args
-        ----
         PoolConfiguration:
 
-        ---
-        client_id -- The client ID of the application provided by Scribe.
+        :param client_id: The client ID of the application provided by Scribe.
 
-        user_pool_id -- The user pool ID provided by Scribe.
+        :param user_pool_id: The user pool ID provided by Scribe.
 
-        identity_pool_id -- The identity pool ID provided by Scribe. (Optional)
+        :param identity_pool_id: The identity pool ID provided by Scribe. (Optional)
         """
         config = Config(signature_version=botocore.UNSIGNED)
         self.client_unsigned = boto3.client(
@@ -115,17 +112,13 @@ def change_password(
     ) -> bool | Challenge:  # pragma: no cover
         """Changes password for a user.
 
-        Args
-        ----
-        username -- Username (usually an email address).
+        :param username: Username (usually an email address).
 
-        password -- Password associated with this username.
+        :param password: Password associated with this username.
 
-        new_password -- New password for this username.
+        :param new_password: New password for this username.
 
-        Returns
-        -------
-        bool
+        :return: bool
         """
         try:
             response_initiate = self.__initiate_auth(username, password)
@@ -174,17 +167,13 @@ def forgot_password(
     ) -> bool:  # pragma: no cover
         """Allows a user to enter a confirmation code sent to their email to reset a forgotten password.
 
-        Args
-        ----
-        username -- Username (usually an email address).
+        :param username: Username (usually an email address).
 
-        password -- Password associated with this username.
+        :param password: Password associated with this username.
 
-        confirmation_code -- Confirmation code sent to the user's email.
+        :param confirmation_code: Confirmation code sent to the user's email.
 
-        Returns
-        -------
-        bool
+        :return: bool
         """
         try:
             self.client_signed.confirm_forgot_password(
@@ -212,19 +201,17 @@ def get_tokens(self, **param: Unpack[RefreshToken]) -> Tokens | Challenge:
     def get_tokens(self, **param) -> Tokens | Challenge:
         """A user gets their tokens (refresh_token, access_token and id_token).
 
-        Args
-        ----
-        username -- Username (usually an email address).
+        It is possible to pass a UsernamePassword or a RefreshToken:
 
-        password -- Password associated with this username.
+        :param UsernamePassword: username (usually an email address) and password (associated with this username).
 
-        Or
+        :param RefreshToken: refresh_token (refresh token to use).
 
-        refresh_token -- Refresh token to use.
+        It returns Tokens or a Challenge:
 
-        Returns
-        -------
-        Tokens -- Dictionary {"refresh_token": "str", "access_token": "str", "id_token": "str"}
+        :return: Tokens -- Dictionary {"refresh_token": "str", "access_token": "str", "id_token": "str"}
+
+        :return: Challenge -- Dictionary { "challenge_name": "str", "session": "str"}
         """
         refresh_token = param.get("refresh_token")
         username = param.get("username")
@@ -243,20 +230,13 @@ def respond_to_auth_challenge_mfa(
     ) -> Tokens:
         """Respond to an MFA auth challenge with a code generated from an auth app (e.g. Authy).
 
-        Args
-        ----
-        username -- Username (usually an email address).
-
-        session -- Challenge session coming from an authentication attempt.
+        :param username: Username (usually an email address).
 
-        code -- Code generated from the auth app.
-        session -- Challenge session.
+        :param session: Challenge session coming from an authentication attempt.
 
-        code -- Code generated from an auth app.
+        :param code: Code generated from the auth app.
 
-        Returns
-        -------
-        Tokens -- Dictionary {"refresh_token": "str", "access_token": "str", "id_token": "str"}
+        :return: Tokens -- Dictionary {"refresh_token": "str", "access_token": "str", "id_token": "str"}
         """
         try:
             response = self.__respond_to_mfa_challenge(username, session, code)
@@ -279,13 +259,9 @@ def revoke_refresh_token(self, refresh_token: str) -> bool:
         """Revokes all of the access tokens generated by the specified refresh token.
         After the token is revoked, the user cannot use the revoked token.
 
-        Args
-        ----
-        refresh_token -- Refresh token to be revoked.
+        :param refresh_token: Refresh token to be revoked.
 
-        Returns
-        -------
-        bool
+        :return: bool
         """
         try:
             self.__revoke_token(refresh_token)
@@ -298,13 +274,9 @@ def revoke_refresh_token(self, refresh_token: str) -> bool:
     def get_federated_id(self, id_token: str) -> str:
         """A user gets their federated id.
 
-        Args
-        ----
-        id_token -- Id token to use.
+        :param id_token: Id token to use.
 
-        Returns
-        -------
-        str
+        :return: str
         """
         if not hasattr(self, "user_pool_id"):
             raise MissingIdException("Missing user pool ID")
@@ -337,15 +309,11 @@ def get_federated_id(self, id_token: str) -> str:
     def get_federated_credentials(self, id: str, id_token: str) -> Credentials:
         """A user gets their federated credentials (AccessKeyId, SecretKey and SessionToken).
 
-        Args
-        ----
-        id -- Federated id.
+        :param id: Federated id.
 
-        id_token -- Id token to use.
+        :param id_token: Id token to use.
 
-        Returns
-        -------
-        Credentials -- Dictionary {"AccessKeyId": "str", "SecretKey": "str", "SessionToken": "str", "Expiration": "str"}
+        :return: Credentials -- Dictionary {"AccessKeyId": "str", "SecretKey": "str", "SessionToken": "str", "Expiration": "str"}
         """
         if not hasattr(self, "user_pool_id"):
             raise MissingIdException("Missing user pool ID")
@@ -395,16 +363,11 @@ def get_federated_credentials(self, id: str, id_token: str) -> Credentials:
     def get_signature_for_request(self, request: AWSRequest, credentials: Credentials):
         """A user gets a signature for a request.
 
-        Args
-        ----
-
-        request -- Request to send.
+        :param request: Request to send.
 
-        credentials -- Credentials for the signature creation.
+        :param credentials: Credentials for the signature creation.
 
-        Returns
-        -------
-        Headers -- Headers containing the signature for the request.
+        :return: Headers -- Headers containing the signature for the request.
         """
         try:
             session = botocore.session.Session()