Docs (#9)

* Add view source links for the generated docs. b/281617372

* remove stray oneof and code-block tags (b/281615596)

* Include generativelanguage_{version} in docs

* Minor doc fixes

Author: MarkDaoust

docs/build_docs.py

@@ -22,6 +22,7 @@
 
 import os
 import pathlib
+import re
 import textwrap
 
 from absl import app
@@ -36,8 +37,6 @@
 
 import yaml
 
-# del google.ai.generativelanguage_v1beta2
-
 google.ai.generativelanguage.__doc__ = """\
 This package, `google.ai.generativelanguage`, is a low-level auto-generated client library for the PaLM API.
 
@@ -132,13 +131,15 @@ def drop_staticmethods(self, parent, children):
                 yield name, value
 
     def __call__(self, path, parent, children):
-        if "generativelanguage" in path or "generativeai" in path:
+        if (
+                any("generativelanguage" in part for part in path)
+                or "generativeai" in path):
             children = self.filter_base_dirs(path, parent, children)
             children = public_api.explicit_package_contents_filter(
                 path, parent, children
             )
 
-        if "generativelanguage" in path:
+        if any("generativelanguage" in part for part in path):
             if "ServiceClient" in path[-1]:
                 children = list(self.drop_staticmethods(parent, children))
 
@@ -154,7 +155,7 @@ def make_default_filters(self):
             public_api.add_proto_fields,
             public_api.filter_builtin_modules,
             public_api.filter_private_symbols,
-            MyFilter(self._base_dir),  # public_api.FilterBaseDirs(self._base_dir),
+            MyFilter(self._base_dir),  # Replaces: public_api.FilterBaseDirs(self._base_dir),
             public_api.FilterPrivateMap(self._private_map),
             public_api.filter_doc_controls_skip,
             public_api.ignore_typing,
@@ -182,12 +183,10 @@ def gen_api_docs():
             pathlib.Path(google.generativeai.__file__).parent,
             pathlib.Path(google.ai.generativelanguage.__file__).parent.parent,
         ),
-        code_url_prefix=(None, None),
+        code_url_prefix=('https://github.com/google/generative-ai-python/blob/master/google/generativeai',
+                         'https://github.com/googleapis/google-cloud-python/tree/main/packages/google-ai-generativelanguage/google/ai'),
         search_hints=_SEARCH_HINTS.value,
         site_path=_SITE_PATH.value,
-        # This callback ensures that docs are only generated for objects that
-        # are explicitly imported in your __init__.py files. There are other
-        # options but this is a good starting point.
         callbacks=[],
     )
 
@@ -213,6 +212,16 @@ def gen_api_docs():
     redirects["redirects"].insert(0, {"from": "/api/python", "to": "/api/"})
     redirects_path.write_text(yaml.dump(redirects))
 
+    # clear `oneof` junk from proto pages
+    for fpath in out_path.rglob('*.md'):
+        old_content = fpath.read_text()
+        new_content = old_content
+        new_content = re.sub(r'\.\. _oneof:.*?\n', '', new_content)
+        new_content = re.sub(r'`oneof`_.*?\n', '', new_content)
+        new_content = re.sub(r'\.\. code-block:: python.*?\n', '', new_content)
+        if new_content != old_content:
+            fpath.write_text(new_content)
+
     print("Output docs to: ", _OUTPUT_DIR.value)
 
 

google/generativeai/types/discuss_types.py

@@ -102,7 +102,7 @@ class ChatResponse(abc.ABC):
     """A chat response from the model.
 
     * Use `response.last` (settable) for easy access to the text of the last response.
-        (`messages[0]['content']`)
+        (`messages[-1]['content']`)
     * Use `response.messages` to access the message history (including `.last`).
     * Use `response.candidates` to access all the responses generated by the model.
 
@@ -112,7 +112,7 @@ class ChatResponse(abc.ABC):
     ```
     import google.generativeai as genai
 
-    genai.configure(api_key=os.environ['API_KEY'])
+    genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
 
     response = genai.chat(messages=["Hello."])
     print(response.last) #  'Hello! What can I help you with?'
@@ -160,9 +160,9 @@ class ChatResponse(abc.ABC):
     temperature: Optional[float]
     candidate_count: Optional[int]
     candidates: List[MessageDict]
+    filters: List[safety_types.ContentFilterDict]
     top_p: Optional[float] = None
     top_k: Optional[float] = None
-    filters: List[safety_types.ContentFilterDict]
 
     @property
     @abc.abstractmethod
@@ -194,4 +194,5 @@ def reply(self, message: MessageOptions) -> "ChatResponse":
 
 
 class AuthorError(Exception):
+    """Raised by the `chat` (or `reply`) functions when the author list can't be normalized."""
     pass

google/generativeai/types/text_types.py

@@ -39,8 +39,8 @@ class Completion(abc.ABC):
     Attributes:
         candidates: A list of candidate text completions generated by the model.
         result: The output of the first candidate,
-        filters: Indicates the reasons why content may have been blocked
-          Either Unspecified, Safety, or Other. See `types.ContentFilter`.
+        filters: Indicates the reasons why content may have been blocked.
+          See `types.BlockedReason`.
         safety_feedback: Indicates which safety settings blocked content in this result.
     """