From 4553d63655975d5223fe73d581b20f133d6e08d7 Mon Sep 17 00:00:00 2001 From: Ailin Venerus Date: Mon, 20 Nov 2023 11:25:51 +0000 Subject: [PATCH] feat: create documentation to be published in ScribeLabs/documentation repo (#103) * fix: complete return type for get_tokens * feat: improve and transform documentation to md files to be published in ScribeLabs/documentation repo * fix: improve documentation and automated commit msg --------- Co-authored-by: Emmanuel Hadoux --- .github/workflows/update-doc.yml | 36 +++++++++++ docs_source/conf.py | 24 +++++--- docs_source/reference.rst | 7 +-- scribeauth/scribeauth.py | 102 +++++++++++-------------------- 4 files changed, 87 insertions(+), 82 deletions(-) create mode 100644 .github/workflows/update-doc.yml diff --git a/.github/workflows/update-doc.yml b/.github/workflows/update-doc.yml new file mode 100644 index 0000000..b46a90b --- /dev/null +++ b/.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/action-pull-request-another-repo@v1.3.1 + 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: 'docs(authPython): Update Auth Python doc' + pr_title: 'Update Auth Python doc' + pull_request_reviewers: 'EHadoux' + user_email: 'ailin@scribelabs.ai' + user_name: 'ailinvenerus' \ No newline at end of file diff --git a/docs_source/conf.py b/docs_source/conf.py index bc5d04b..5464164 100644 --- a/docs_source/conf.py +++ b/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" diff --git a/docs_source/reference.rst b/docs_source/reference.rst index b134831..a9bda82 100644 --- a/docs_source/reference.rst +++ b/docs_source/reference.rst @@ -1,7 +1,6 @@ Methods Reference ================= -.. currentmodule:: scribeauth -.. autoclass:: ScribeAuth - :members: - :special-members: __init__ \ No newline at end of file +.. autoclass:: scribeauth.ScribeAuth + :members: + :special-members: __init__ \ No newline at end of file diff --git a/scribeauth/scribeauth.py b/scribeauth/scribeauth.py index 6029cd2..9fb06d5 100644 --- a/scribeauth/scribeauth.py +++ b/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,20 @@ 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 username: Username (usually an email address). + :param password: Password (associated with this username). Or - refresh_token -- Refresh token to use. + :param refresh_token: Refresh Token to use. - Returns - ------- - Tokens -- Dictionary {"refresh_token": "str", "access_token": "str", "id_token": "str"} + It returns Tokens or a Challenge: + + :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 +233,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). + :param username: Username (usually an email address). - session -- Challenge session coming from an authentication attempt. + :param session: Challenge session coming from an authentication attempt. - code -- Code generated from the auth app. - session -- Challenge session. + :param code: Code generated from the auth app. - code -- Code generated from an 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 +262,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 +277,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 +312,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 +366,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()