docs: Add API reference docs (#51)

* docs: Add API reference docs

* update header & pyproject

---------

Co-authored-by: Averi Kitsch <akitsch@google.com>

.github/header-checker-lint.yml

@@ -9,13 +9,13 @@ sourceFileExtensions:
   - "proto"
   - "Dockerfile"
   - "py"
-  - "html"
   - "text"
 ignoreFiles:
   - ".github/release-please.yml"
   - ".github/release-trigger.yml"
   - ".github/header-checker-lint.yml"
   - ".github/sync-repo-settings.yaml"
+  - ".github/workflows/docs.yml"
   - ".kokoro/**"
   - "**/requirements.txt"
   - "**/requirements-test.txt"

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+on:
+  pull_request:
+    branches:
+      - main
+name: docs
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.9"
+    - name: Install nox
+      run: |
+        python -m pip install --upgrade setuptools pip wheel
+        python -m pip install nox
+    - name: Run docs
+      run: |
+        nox -s docs
+  docfx:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+    - name: Install nox
+      run: |
+        python -m pip install --upgrade setuptools pip wheel
+        python -m pip install nox
+    - name: Run docfx
+      run: |
+        nox -s docfx

.kokoro/docker/docs/requirements.in

@@ -0,0 +1 @@
+nox

.kokoro/docker/docs/requirements.txt

@@ -0,0 +1,38 @@
+#
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
+#
+#    pip-compile --allow-unsafe --generate-hashes requirements.in
+#
+argcomplete==3.3.0 \
+    --hash=sha256:c168c3723482c031df3c207d4ba8fa702717ccb9fc0bfe4117166c1f537b4a54 \
+    --hash=sha256:fd03ff4a5b9e6580569d34b273f741e85cd9e072f3feeeee3eba4891c70eda62
+    # via nox
+colorlog==6.8.2 \
+    --hash=sha256:3e3e079a41feb5a1b64f978b5ea4f46040a94f11f0e8bbb8261e3dbbeca64d44 \
+    --hash=sha256:4dcbb62368e2800cb3c5abd348da7e53f6c362dda502ec27c560b2e58a66bd33
+    # via nox
+distlib==0.3.8 \
+    --hash=sha256:034db59a0b96f8ca18035f36290806a9a6e6bd9d1ff91e45a7f172eb17e51784 \
+    --hash=sha256:1530ea13e350031b6312d8580ddb6b27a104275a31106523b8f123787f494f64
+    # via virtualenv
+filelock==3.14.0 \
+    --hash=sha256:43339835842f110ca7ae60f1e1c160714c5a6afd15a2873419ab185334975c0f \
+    --hash=sha256:6ea72da3be9b8c82afd3edcf99f2fffbb5076335a5ae4d03248bb5b6c3eae78a
+    # via virtualenv
+nox==2024.4.15 \
+    --hash=sha256:6492236efa15a460ecb98e7b67562a28b70da006ab0be164e8821177577c0565 \
+    --hash=sha256:ecf6700199cdfa9e5ea0a41ff5e6ef4641d09508eda6edb89d9987864115817f
+    # via -r requirements.in
+packaging==24.0 \
+    --hash=sha256:2ddfb553fdf02fb784c234c7ba6ccc288296ceabec964ad2eae3777778130bc5 \
+    --hash=sha256:eb82c5e3e56209074766e6885bb04b8c38a0c015d0a30036ebe7ece34c9989e9
+    # via nox
+platformdirs==4.2.1 \
+    --hash=sha256:031cd18d4ec63ec53e82dceaac0417d218a6863f7745dfcc9efe7793b7039bdf \
+    --hash=sha256:17d5a1161b3fd67b390023cb2d3b026bbd40abde6fdb052dfbd3a29c3ba22ee1
+    # via virtualenv
+virtualenv==20.26.1 \
+    --hash=sha256:604bfdceaeece392802e6ae48e69cec49168b9c5f4a44e483963f9242eb0e78b \
+    --hash=sha256:7aa9982a728ae5892558bff6a2839c00b9ed145523ece2274fad6f414690ae75
+    # via nox

.kokoro/docs/common.cfg

@@ -30,9 +30,9 @@ env_vars: {
 
 env_vars: {
     key: "V2_STAGING_BUCKET"
-    # Push non-cloud library docs to `docs-staging-v2-staging` instead of the
+    # Push non-cloud library docs to `docs-staging-v2` instead of the
     # Cloud RAD bucket `docs-staging-v2`
-    value: "docs-staging-v2-staging"
+    value: "docs-staging-v2"
 }
 
 # It will upload the docker image after successful builds.

.kokoro/publish-docs.sh

@@ -27,14 +27,15 @@ python3 -m nox --version
 # build docs
 nox -s docs
 
-VERSION=$(python -c "import langchain_google_el_carro;print(langchain_google_el_carro.__version__)")
+python3 -m pip install .
+VERSION=$(python3 -c "import langchain_google_el_carro;print(langchain_google_el_carro.__version__)")
 
 # create metadata
 python3 -m docuploader create-metadata \
   --name=$(jq --raw-output '.name // empty' .repo-metadata.json) \
   --version=$VERSION \
   --language=$(jq --raw-output '.language // empty' .repo-metadata.json) \
-  --distribution-name=$(yq -oy '.project.name'  pyproject.toml) \
+  --distribution-name=$(jq --raw-output '.distribution_name // empty' .repo-metadata.json) \
   --product-page=$(jq --raw-output '.product_documentation // empty' .repo-metadata.json) \
   --github-repository=$(jq --raw-output '.repo // empty' .repo-metadata.json) \
   --issue-tracker=$(jq --raw-output '.issue_tracker // empty' .repo-metadata.json)
@@ -53,7 +54,7 @@ python3 -m docuploader create-metadata \
   --name=$(jq --raw-output '.name // empty' .repo-metadata.json) \
   --version=$VERSION \
   --language=$(jq --raw-output '.language // empty' .repo-metadata.json) \
-  --distribution-name=$(yq -oy '.project.name'  pyproject.toml) \
+  --distribution-name=$(jq --raw-output '.distribution_name // empty' .repo-metadata.json) \
   --product-page=$(jq --raw-output '.product_documentation // empty' .repo-metadata.json) \
   --github-repository=$(jq --raw-output '.repo // empty' .repo-metadata.json) \
   --issue-tracker=$(jq --raw-output '.issue_tracker // empty' .repo-metadata.json)

.trampolinerc

@@ -0,0 +1,61 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Add required env vars here.
+required_envvars+=(
+)
+
+# Add env vars which are passed down into the container here.
+pass_down_envvars+=(
+    "NOX_SESSION"
+    ###############
+    # Docs builds
+    ###############
+    "STAGING_BUCKET"
+    "V2_STAGING_BUCKET"
+    ##################
+    # Samples builds
+    ##################
+    "INSTALL_LIBRARY_FROM_SOURCE"
+    "RUN_TESTS_SESSION"
+    "BUILD_SPECIFIC_GCLOUD_PROJECT"
+    # Target directories.
+    "RUN_TESTS_DIRS"
+    # The nox session to run.
+    "RUN_TESTS_SESSION"
+)
+
+# Prevent unintentional override on the default image.
+if [[ "${TRAMPOLINE_IMAGE_UPLOAD:-false}" == "true" ]] && \
+   [[ -z "${TRAMPOLINE_IMAGE:-}" ]]; then
+   echo "Please set TRAMPOLINE_IMAGE if you want to upload the Docker image."
+   exit 1
+fi
+
+# Define the default value if it makes sense.
+if [[ -z "${TRAMPOLINE_IMAGE_UPLOAD:-}" ]]; then
+    TRAMPOLINE_IMAGE_UPLOAD=""
+fi
+
+if [[ -z "${TRAMPOLINE_IMAGE:-}" ]]; then
+    TRAMPOLINE_IMAGE=""
+fi
+
+if [[ -z "${TRAMPOLINE_DOCKERFILE:-}" ]]; then
+    TRAMPOLINE_DOCKERFILE=""
+fi
+
+if [[ -z "${TRAMPOLINE_BUILD_FILE:-}" ]]; then
+    TRAMPOLINE_BUILD_FILE=""
+fi