docs: fix docs arrangement (#35)

* docs: fix docs arrangement * updated documentation * lint fix --------- Co-authored-by: Gal Zahavi <38544478+galz10@users.noreply.github.com>
googleapis · Jan 31, 2023 · 51dd7ff · 51dd7ff
1 parent 20b1e44
commit 51dd7ff
Show file tree

Hide file tree

Showing 9 changed files with 65 additions and 30 deletions.
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1 @@
+../CHANGELOG.md
diff --git a/docs/documentai_toolbox/document.rst b/docs/documentai_toolbox/document.rst
@@ -0,0 +1,8 @@
+Document AI Toolbox Document Wrapper
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: google.cloud.documentai_toolbox.wrappers.document
+  :members:
+  :private-members:
+  :noindex:
+
diff --git a/docs/documentai_toolbox/entity.rst b/docs/documentai_toolbox/entity.rst
@@ -0,0 +1,8 @@
+Document AI Toolbox Entity Wrapper
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: google.cloud.documentai_toolbox.wrappers.entity
+  :members:
+  :private-members:
+  :noindex:
+
diff --git a/docs/documentai_toolbox/page.rst b/docs/documentai_toolbox/page.rst
@@ -0,0 +1,8 @@
+Document AI Toolbox Page Wrapper
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: google.cloud.documentai_toolbox.wrappers.page
+  :members:
+  :private-members:
+  :noindex:
+
diff --git a/docs/documentai_toolbox/wrappers.rst b/docs/documentai_toolbox/wrappers.rst
@@ -1,6 +1,9 @@
 Document AI Toolbox Client Types
 ================================
 
-.. automodule:: google.cloud.documentai_toolbox.wrappers
-  :members:
-  :noindex:
+.. toctree::
+  :maxdepth: 2
+
+  document
+  entity
+  page
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,15 +3,13 @@
 API Reference
 -------------
 .. toctree::
-    :maxdepth: 2
+  :maxdepth: 2
 
-    documentai_toolbox/wrappers
+  documentai_toolbox/wrappers
 
 Changelog
 ---------
-
-For a list of all ``google-cloud-documentai-toolbox`` releases:
-
 .. toctree::
-    :maxdepth: 2
+  :maxdepth: 2
 
+  changelog
diff --git a/google/cloud/documentai_toolbox/wrappers/document.py b/google/cloud/documentai_toolbox/wrappers/document.py
@@ -70,7 +70,12 @@ def _pages_from_shards(shards: List[documentai.Document]) -> List[Page]:
 
 
 def _get_storage_client():
-    """Returns a Storage client with custom user agent header."""
+    r"""Returns a Storage client with custom user agent header.
+
+    Returns:
+        storage.Client.
+
+    """
     user_agent = f"{constants.USER_AGENT_PRODUCT}/{documentai_toolbox.__version__}"
 
     info = client_info.ClientInfo(
@@ -88,13 +93,13 @@ def _get_bytes(gcs_bucket_name: str, gcs_prefix: str) -> List[bytes]:
         gcs_bucket_name (str):
             Required. The name of the gcs bucket.
 
-            Format: `gs://{bucket}/{optional_folder}/{target_folder}/`
-                    where gcs_bucket_name=`{bucket}`.
+            Format: gs://{bucket}/{optional_folder}/{target_folder}/
+                    where gcs_bucket_name={bucket} .
         gcs_prefix (str):
             Required. The prefix of the json files in the target_folder
 
-            Format: `gs://{bucket}/{optional_folder}/{target_folder}/`
-                    where gcs_prefix=`{optional_folder}/{target_folder}/`.
+            Format: gs://{bucket}/{optional_folder}/{target_folder}/
+                    where gcs_prefix={optional_folder}/{target_folder}/ .
     Returns:
         List[bytes]:
             A list of bytes.
@@ -120,13 +125,13 @@ def _get_shards(gcs_bucket_name: str, gcs_prefix: str) -> List[documentai.Docume
         gcs_bucket_name (str):
             Required. The name of the gcs bucket.
 
-            Format: `gs://{bucket}/{optional_folder}/{target_folder}/`
-                    where gcs_bucket_name=`{bucket}`.
+            Format: gs://{bucket}/{optional_folder}/{target_folder}/
+                    where gcs_bucket_name={bucket}.
         gcs_prefix (str):
             Required. The prefix of the json files in the target_folder.
 
-            Format: `gs://{bucket}/{optional_folder}/{target_folder}/`
-                    where gcs_prefix=`{optional_folder}/{target_folder}/`.
+            Format: gs://{bucket}/{optional_folder}/{target_folder}/
+                    where gcs_prefix={optional_folder}/{target_folder}/.
     Returns:
         List[google.cloud.documentai.Document]:
             A list of documentai.Documents.
@@ -154,13 +159,13 @@ def print_gcs_document_tree(gcs_bucket_name: str, gcs_prefix: str) -> None:
         gcs_bucket_name (str):
             Required. The name of the gcs bucket.
 
-            Format: `gs://{bucket}/{optional_folder}/{target_folder}/`
-                    where gcs_bucket_name=`{bucket}`.
+            Format: gs://{bucket}/{optional_folder}/{target_folder}/
+                    where gcs_bucket_name={bucket}.
         gcs_prefix (str):
             Required. The prefix of the json files in the target_folder.
 
-            Format: `gs://{bucket}/{optional_folder}/{target_folder}/`
-                    where gcs_prefix=`{optional_folder}/{target_folder}/`.
+            Format: gs://{bucket}/{optional_folder}/{target_folder}/
+                    where gcs_prefix={optional_folder}/{target_folder}/ .
     Returns:
         None.
 
@@ -222,15 +227,15 @@ class Document:
         gcs_bucket_name (Optional[str]):
             Optional. The name of the gcs bucket.
 
-            Format: `gs://{bucket}/{optional_folder}/{target_folder}/`
-                    where gcs_bucket_name=`{bucket}`.
+            Format: gs://{bucket}/{optional_folder}/{target_folder}/
+                    where gcs_bucket_name={bucket}.
         gcs_prefix (Optional[str]):
             Optional. The prefix of the json files in the target_folder.
 
-            Format: `gs://{bucket}/{optional_folder}/{target_folder}/`
-                    where gcs_prefix=`{optional_folder}/{target_folder}/`.
+            Format: gs://{bucket}/{optional_folder}/{target_folder}/
+                    where gcs_prefix={optional_folder}/{target_folder}/.
 
-            For more information please take a look at https://cloud.google.com/storage/docs/json_api/v1/objects/list
+            For more information please take a look at https://cloud.google.com/storage/docs/json_api/v1/objects/list .
         pages: (List[Page]):
             A list of Pages in the Document.
         entities: (List[Entity]):

diff --git a/google/cloud/documentai_toolbox/wrappers/entity.py b/google/cloud/documentai_toolbox/wrappers/entity.py
@@ -28,10 +28,10 @@ class Entity:
         documentai_entity (google.cloud.documentai.Document.Entity):
             Required. The original google.cloud.documentai.Document.Entity object.
         type_ (str):
-            Required. Entity type from a schema e.g. ``Address``.
+            Required. Entity type from a schema e.g. "Address".
         mention_text (str):
-            Optional. Text value in the document e.g.
-            ``1600 Amphitheatre Pkwy``. If the entity is not present in
+            Optional. Text value in the document e.g. "1600 Amphitheatre Pkwy".
+            If the entity is not present in
             the document, this field will be empty.
     """
     documentai_entity: documentai.Document.Entity = dataclasses.field(repr=False)

diff --git a/google/cloud/documentai_toolbox/wrappers/page.py b/google/cloud/documentai_toolbox/wrappers/page.py
@@ -139,6 +139,7 @@ def _table_wrapper_from_documentai_table(
 @dataclasses.dataclass
 class Paragraph:
     """Represents a wrapped documentai.Document.Page.Paragraph.
+
     Attributes:
         documentai_paragraph (google.cloud.documentai.Document.Page.Paragraph):
             Required. The original google.cloud.documentai.Document.Page.Paragraph object.
@@ -153,6 +154,7 @@ class Paragraph:
 @dataclasses.dataclass
 class Line:
     """Represents a wrapped documentai.Document.Page.Line.
+
     Attributes:
         documentai_line (google.cloud.documentai.Document.Page.Line):
             Required. The original google.cloud.documentai.Document.Page.Line object.
@@ -198,6 +200,7 @@ def _get_paragraphs(
     paragraphs: List[documentai.Document.Page.Paragraph], text: str
 ) -> List[Paragraph]:
     r"""Returns a list of Paragraph.
+
     Args:
         paragraphs (List[documentai.Document.Page.Paragraph]):
             Required. A list of documentai.Document.Page.Paragraph objects.
@@ -225,6 +228,7 @@ def _get_paragraphs(
 
 def _get_lines(lines: List[documentai.Document.Page.Line], text: str) -> List[Line]:
     r"""Returns a list of Line.
+
     Args:
         lines (List[documentai.Document.Page.Line]):
             Required. A list of documentai.Document.Page.Line objects.