feat: Python API Docs on GitHub Pages

.github/workflows/gh_pages_doc.yaml

@@ -0,0 +1,45 @@
+name: Deploy Sphinx documentation to Pages
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          pip install sphinx myst-parser[linkify] myst_nb
+
+      - name: Build the documentation
+        run: |
+          cd docs
+          make html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "docs/_build/html"
+
+  pages:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,70 @@
+import re
+
+project = 'Google Generative AI - Python'
+copyright = '2024, Google LLC'
+author = 'Google LLC'
+
+extensions = [
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.coverage',
+    'myst_parser',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+    ]
+
+# autosectionlabel_prefix_document = True
+
+myst_url_schemes = ["http", "https", "mailto"]
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "fieldlist",
+    "html_image",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "tasklist",
+    "substitution",
+    "linkify",
+]
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-header-anchors
+# Controls allowable header anchors in markdown files. Value allows header anchors for h1 - h6
+myst_heading_anchors = 6
+suppress_warnings = ["myst.xref_missing", "myst.iref_ambiguous"]
+
+source_suffix = {'.md': 'markdown',}
+master_doc = 'index' #'api/google/generativeai'
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+html_theme = 'alabaster'
+# html_static_path = ['_static']
+
+
+def set_relative_links(app, docname, source):
+    source[0] = source[0].replace(
+        '../google/generativeai/',
+        '/api/google/generativeai/'
+    )
+
+def replace_md_links(app, pagename, templatename, context, doctree):
+    """Replaces all .md links with .html in the final HTML output."""
+    if 'body' in context:
+        # Pattern to identify and replace <a href="*.md#anchor"> links
+        pattern = re.compile(r'<a href="([^"]+)\.md(#[^"]*)?">')
+
+        # Function to replace matched .md links with .html links
+        def md_to_html(match):
+            # Get the base link and optional fragment
+            base_link = match.group(1)
+            fragment = match.group(2) or ""
+            # Replace .md with .html and retain the fragment if present
+            return f'<a href="/generative-ai-python{base_link}.html{fragment}" class="reference internal">'
+
+        # Apply the replacement to all <a> links in the HTML body
+        context['body'] = pattern.sub(md_to_html, context['body'])
+
+def setup(app):
+    app.connect('html-page-context', replace_md_links)
+    app.connect('source-read', set_relative_links)

docs/index.md

@@ -0,0 +1,138 @@
+description: Google AI Python SDK
+
+<div itemscope itemtype="http://developers.google.com/ReferenceObject">
+<meta itemprop="name" content="google.generativeai" />
+<meta itemprop="path" content="Stable" />
+<meta itemprop="property" content="__version__"/>
+<meta itemprop="property" content="annotations"/>
+</div>
+
+# Module: google.generativeai
+
+<!-- Insert buttons and diff -->
+
+<table class="tfo-notebook-buttons tfo-api nocontent" align="left">
+<td>
+  <a target="_blank" href="https://github.com/google/generative-ai-python/blob/master/google/generativeai/__init__.py">
+    <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
+    View source on GitHub
+  </a>
+</td>
+</table>
+
+
+
+Google AI Python SDK
+
+
+
+## Setup
+
+```posix-terminal
+pip install google-generativeai
+```
+
+## GenerativeModel
+
+Use `genai.GenerativeModel` to access the API:
+
+```
+import google.generativeai as genai
+import os
+
+genai.configure(api_key=os.environ['API_KEY'])
+
+model = genai.GenerativeModel(model_name='gemini-1.5-flash')
+response = model.generate_content('Teach me about how an LLM works')
+
+print(response.text)
+```
+
+See the [python quickstart](https://ai.google.dev/tutorials/python_quickstart) for more details.
+
+## Modules
+
+[`protos`](../google/generativeai/protos.md) module: This module provides low level access to the ProtoBuffer "Message" classes used by the API.
+
+[`types`](../google/generativeai/types.md) module: A collection of type definitions used throughout the library.
+
+## Classes
+
+[`class ChatSession`](../google/generativeai/ChatSession.md): Contains an ongoing conversation with the model.
+
+[`class GenerationConfig`](../google/generativeai/types/GenerationConfig.md): A simple dataclass used to configure the generation parameters of <a href="../google/generativeai/GenerativeModel.md#generate_content"><code>GenerativeModel.generate_content</code></a>.
+
+[`class GenerativeModel`](../google/generativeai/GenerativeModel.md): The `genai.GenerativeModel` class wraps default parameters for calls to <a href="../google/generativeai/GenerativeModel.md#generate_content"><code>GenerativeModel.generate_content</code></a>, <a href="../google/generativeai/GenerativeModel.md#count_tokens"><code>GenerativeModel.count_tokens</code></a>, and <a href="../google/generativeai/GenerativeModel.md#start_chat"><code>GenerativeModel.start_chat</code></a>.
+
+## Functions
+
+[`chat(...)`](../google/generativeai/chat.md): Calls the API to initiate a chat with a model using provided parameters
+
+[`chat_async(...)`](../google/generativeai/chat_async.md): Calls the API to initiate a chat with a model using provided parameters
+
+[`configure(...)`](../google/generativeai/configure.md): Captures default client configuration.
+
+[`count_message_tokens(...)`](../google/generativeai/count_message_tokens.md): Calls the API to calculate the number of tokens used in the prompt.
+
+[`count_text_tokens(...)`](../google/generativeai/count_text_tokens.md): Calls the API to count the number of tokens in the text prompt.
+
+[`create_tuned_model(...)`](../google/generativeai/create_tuned_model.md): Calls the API to initiate a tuning process that optimizes a model for specific data, returning an operation object to track and manage the tuning progress.
+
+[`delete_file(...)`](../google/generativeai/delete_file.md): Calls the API to permanently delete a specified file using a supported file service.
+
+[`delete_tuned_model(...)`](../google/generativeai/delete_tuned_model.md): Calls the API to delete a specified tuned model
+
+[`embed_content(...)`](../google/generativeai/embed_content.md): Calls the API to create embeddings for content passed in.
+
+[`embed_content_async(...)`](../google/generativeai/embed_content_async.md): Calls the API to create async embeddings for content passed in.
+
+[`generate_embeddings(...)`](../google/generativeai/generate_embeddings.md): Calls the API to create an embedding for the text passed in.
+
+[`generate_text(...)`](../google/generativeai/generate_text.md): Calls the API to generate text based on the provided prompt.
+
+[`get_base_model(...)`](../google/generativeai/get_base_model.md): Calls the API to fetch a base model by name.
+
+[`get_file(...)`](../google/generativeai/get_file.md): Calls the API to retrieve a specified file using a supported file service.
+
+[`get_model(...)`](../google/generativeai/get_model.md): Calls the API to fetch a model by name.
+
+[`get_operation(...)`](../google/generativeai/get_operation.md): Calls the API to get a specific operation
+
+[`get_tuned_model(...)`](../google/generativeai/get_tuned_model.md): Calls the API to fetch a tuned model by name.
+
+[`list_files(...)`](../google/generativeai/list_files.md): Calls the API to list files using a supported file service.
+
+[`list_models(...)`](../google/generativeai/list_models.md): Calls the API to list all available models.
+
+[`list_operations(...)`](../google/generativeai/list_operations.md): Calls the API to list all operations
+
+[`list_tuned_models(...)`](../google/generativeai/list_tuned_models.md): Calls the API to list all tuned models.
+
+[`update_tuned_model(...)`](../google/generativeai/update_tuned_model.md): Calls the API to push updates to a specified tuned model where only certain attributes are updatable.
+
+[`upload_file(...)`](../google/generativeai/upload_file.md): Calls the API to upload a file using a supported file service.
+
+
+
+<!-- Tabular view -->
+ <table class="responsive fixed orange">
+<colgroup><col width="214px"><col></colgroup>
+<tr><th colspan="2"><h2 class="add-link">Other Members</h2></th></tr>
+
+<tr>
+<td>
+__version__<a id="__version__"></a>
+</td>
+<td>
+`'0.7.2'`
+</td>
+</tr><tr>
+<td>
+annotations<a id="annotations"></a>
+</td>
+<td>
+Instance of `__future__._Feature`
+</td>
+</tr>
+</table>
+

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd