Merge pull request #180 from supabase-community/j0/add_docs

feat: add docs for GoTrue
supabase · Dec 12, 2022 · f7eade8 · f7eade8
2 parents dff74c6 + df4ab8f
commit f7eade8
Show file tree

Hide file tree

Showing 12 changed files with 167 additions and 83 deletions.
diff --git a/docs/source/api/api.rst b/docs/source/api/api.rst
@@ -0,0 +1,5 @@
+API
+======
+
+.. autoclass:: gotrue._async.api.AsyncGoTrueAPI
+    :inherited-members:
diff --git a/docs/source/api/client.rst b/docs/source/api/client.rst
@@ -0,0 +1,9 @@
+Client
+======
+
+The entrypoint to the library is the Client class. To interact with the Gotrue API, you make an instance of this class.
+
+
+.. autoclass:: gotrue.AsyncGoTrueClient
+    :members:
+    :inherited-members:
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -0,0 +1,14 @@
+API Reference
+=============
+
+.. note::
+    The library offers both synchronous and asynchronous clients.
+    Note that the synchronous and asynchronous classes all provide the exact same interface.
+    Only the async client and it's methods are documented here.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference:
+
+      Client <client>
+      API <api>
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -17,23 +17,29 @@
 # -- Project information -----------------------------------------------------
 
 project = "gotrue"
-copyright = "2021, Joel Lee"
-author = "Joel Lee"
+copyright = (
+    "2022, Anand Krishna, Daniel Reinón García, Joel Lee, Leynier Gutiérrez González"
+)
+author = "Anand Krishna, Daniel Reinón García, Joel Lee, Leynier Gutiérrez González"
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.extlinks",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # -- Options for HTML output -------------------------------------------------
 

diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -0,0 +1,14 @@
+Examples(WIP)
+=============
+
+.. note::
+    The library offers both synchronous and asynchronous clients.
+    Note that the synchronous and asynchronous classes all provide the exact same interface.
+    Only the async client and it's methods are documented here.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference:
+
+      API </api/api>
+      Client </api/client>
diff --git a/docs/source/gotrue.rst b/docs/source/gotrue.rst
@@ -0,0 +1,53 @@
+gotrue package
+==============
+
+Submodules
+----------
+
+gotrue.constants module
+-----------------------
+
+.. automodule:: gotrue.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+gotrue.exceptions module
+------------------------
+
+.. automodule:: gotrue.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+gotrue.helpers module
+---------------------
+
+.. automodule:: gotrue.helpers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+gotrue.http\_clients module
+---------------------------
+
+.. automodule:: gotrue.http_clients
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+gotrue.types module
+-------------------
+
+.. automodule:: gotrue.types
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: gotrue
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,8 +11,9 @@ Welcome to gotrue's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   usage/client
-   usage/admin
+      API Reference </api/index>
+      Examples </examples/index>
+      Miscellaneous Modules <modules>
 
 
 

diff --git a/docs/source/modules.rst b/docs/source/modules.rst
@@ -0,0 +1,7 @@
+gotrue-py
+=========
+
+.. toctree::
+   :maxdepth: 4
+
+   gotrue
diff --git a/docs/source/usage/admin.rst b/docs/source/usage/admin.rst
diff --git a/docs/source/usage/client.rst b/docs/source/usage/client.rst
diff --git a/gotrue/_async/api.py b/gotrue/_async/api.py
@@ -60,8 +60,8 @@ async def create_user(self, *, attributes: UserAttributes) -> User:
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         data = attributes.dict()
@@ -82,8 +82,8 @@ async def list_users(self) -> List[User]:
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         url = f"{self.url}/admin/users"
@@ -125,8 +125,8 @@ async def sign_up_with_email(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         query_string = ""
@@ -164,9 +164,10 @@ async def sign_in_with_email(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
+
         headers = self.headers
         query_string = "?grant_type=password"
         if redirect_to:
@@ -203,8 +204,8 @@ async def sign_up_with_phone(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         data = {"phone": phone, "password": password, "data": data}
@@ -235,8 +236,8 @@ async def sign_in_with_phone(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         data = {"phone": phone, "password": password}
         url = f"{self.url}/token?grant_type=password"
@@ -262,8 +263,8 @@ async def send_magic_link_email(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         query_string = ""
@@ -285,8 +286,8 @@ async def send_mobile_otp(self, *, phone: str, create_user: bool) -> None:
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         data = {"phone": phone, "create_user": create_user}
@@ -320,8 +321,8 @@ async def verify_mobile_otp(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         data = {
@@ -362,8 +363,8 @@ async def invite_user_by_email(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         query_string = ""
@@ -392,8 +393,8 @@ async def reset_password_for_email(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         query_string = ""
@@ -422,8 +423,7 @@ def _create_request_headers(self, *, jwt: str) -> Dict[str, str]:
             The headers required for a successful request statement with the
             supabase backend.
         """
-        headers = {**self.headers}
-        headers["Authorization"] = f"Bearer {jwt}"
+        headers = {**self.headers, "Authorization": f"Bearer {jwt}"}
         return headers
 
     async def sign_out(self, *, jwt: str) -> None:
@@ -463,8 +463,8 @@ async def get_url_for_provider(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         url_params = [f"provider={encode_uri_component(provider)}"]
         if redirect_to:
@@ -489,8 +489,8 @@ async def get_user(self, *, jwt: str) -> User:
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self._create_request_headers(jwt=jwt)
         url = f"{self.url}/user"
@@ -520,8 +520,8 @@ async def update_user(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self._create_request_headers(jwt=jwt)
         data = attributes.dict()
@@ -549,8 +549,8 @@ async def delete_user(self, *, uid: str, jwt: str) -> None:
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self._create_request_headers(jwt=jwt)
         url = f"{self.url}/admin/users/{uid}"
@@ -572,8 +572,8 @@ async def refresh_access_token(self, *, refresh_token: str) -> Session:
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         data = {"refresh_token": refresh_token}
         url = f"{self.url}/token?grant_type=refresh_token"
@@ -614,8 +614,8 @@ async def generate_link(
 
         Raises
         ------
-        error : APIError
-            If an error occurs
+        APIError
+            If an error occurs.
         """
         headers = self.headers
         data = {