Update How-to Guides (#417)

- reduce the number of API keys needed (Use simple tool)
- make everything "tool use" oriented rather than split across agent executor, function calling, tool use, etc.
- Reorg navbar and index
- Fixup some docstrings
- Add more links to ref docs
- Mix up models used
- Simplify a few examples

.github/workflows/deploy_docs.yml

@@ -3,7 +3,10 @@ name: Deploy Docs
 on:
   push:
     branches:
-      - main 
+      - main
+  pull_request:
+    branches:
+      - main
   workflow_dispatch:
 
 permissions:
@@ -19,33 +22,47 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-        - uses: actions/checkout@v4
-        - name: install deps
-          run: |
-            pip install poetry poethepoet
-        - name: Set up Python
-          uses: actions/setup-python@v4
-          with:
-            python-version: 3.12
-            cache: poetry
-            cache-dependency-path: 'poetry.lock'
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-        - name: Poetry install
-          run: |
-            poetry install
-            poetry run pip install -r docs/docs-requirements.txt
+      - name: Install dependencies
+        run: |
+          pip install poetry poethepoet
 
-        - name: Build site
-          run: make build-docs
-        
-        - name: Configure GitHub Pages
-          uses: actions/configure-pages@v4
-        
-        - name: Upload Pages Artifact
-          uses: actions/upload-pages-artifact@v3
-          with:
-            path: ./docs/site/
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.12
+          cache: poetry
+          cache-dependency-path: "poetry.lock"
 
-        - name: Deploy to GitHub Pages
-          id: deployment
-          uses: actions/deploy-pages@v4
+      - name: Poetry install
+        run: |
+          poetry install
+          poetry run pip install -r docs/docs-requirements.txt
+
+      - name: Build site
+        run: make build-docs
+
+      - name: Configure GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@v4
+
+      - name: Upload Pages Artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/site/
+
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+      - name: Deploy Pull Request Preview
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v2
+        with:
+          name: pr-preview-${{ github.event.number }}
+          path: ./docs/site/