docs: update Llama Deploy documentation build (#16403)

.readthedocs.yaml

@@ -10,12 +10,12 @@ build:
   tools:
     python: "3.12"
   jobs:
+    post_create_environment:
+      - python -m pip install poetry
+    post_install:
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH cd docs && poetry install
     pre_build:
-      - python docs/merge_llama_deploy_docs.py
+      - cd docs && poetry run merge-llama-deploy-docs
 
 mkdocs:
   configuration: docs/mkdocs.yml
-
-python:
-  install:
-    - requirements: docs/requirements.txt

docs/.gitignore

@@ -0,0 +1,4 @@
+# docs build
+docs/api_reference/llama_deploy/*
+docs/module_guides/llama_deploy/*
+llama_deploy

docs/README.md

@@ -0,0 +1,67 @@
+# Documentation
+
+This directory contains the documentation source code for LlamaIndex, available at https://docs.llamaindex.ai.
+
+This guide is made for anyone who's interested in running LlamaIndex documentation locally,
+making changes to it and making contributions. LlamaIndex is made by the thriving community
+behind it, and you're always welcome to make contributions to the project and the
+documentation.
+
+## Build Docs
+
+If you haven't already, clone the LlamaIndex Github repo to a local directory:
+
+```
+git clone https://github.com/run-llama/llama_index.git && cd llama_index
+```
+
+Documentation has its own, dedicated Python virtual environment, and all the tools and scripts are available from the
+`docs` directory:
+
+```
+cd llama_index/docs
+```
+
+From now on, we assume all the commands will be executed from the `docs` directory.
+
+Install all dependencies required for building docs (mainly `mkdocs` and its extension):
+
+- [Install poetry](https://python-poetry.org/docs/#installation) - this will help you manage package dependencies
+- `poetry install` - this will install all dependencies needed for building docs
+
+To build the docs and browse them locally run:
+
+```
+poetry run serve
+```
+
+During the build, notebooks are converted to documentation pages, and this takes several minutes. If you're not
+working on the "Examples" section of the documentation, you can run the same command with `--skip-notebooks`:
+
+```
+poetry run serve --skip-notebooks
+```
+
+> [!IMPORTANT]
+> Building the documentation takes a while, so make sure you see the following output before opening the browser:
+>
+> ```
+> ...
+> INFO    -  Documentation built in 53.32 seconds
+> INFO    -  [16:18:17] Watching paths for changes: 'docs'
+> INFO    -  [16:18:17] Serving on http://127.0.0.1:8000/en/stable/
+> ```
+
+You can now open your browser at http://localhost:8000/ to view the generated docs. The local server will rebuild the
+docs and refresh your browser every time you make changes to the docs.
+
+## Configuration
+
+Part of the configuration in `mkdocs.yml` is generated by a script that takes care of keeping the examples in sync as
+well as the API reference for all the packages in this repo.
+
+Running the command `poetry run prepare-for-build` from the `docs` folder will update the `mkdocs.yml` with the latest
+changes, along with writing new api reference files.
+
+> [!TIP]
+> As a contributor, you wouldn't normally need to run this script, feel free to ask for help in the PR.

docs/docs/DOCS_README.md

@@ -1,9 +1,6 @@
-# Documentation Guide
+# Documentation
 
-## A guide for docs contributors
-
-The `docs` directory contains the sphinx source text for LlamaIndex docs, visit
-https://docs.llamaindex.ai/en/stable/ to read the full documentation.
+This directory contains the documentation source code for LlamaIndex, available at https://docs.llamaindex.ai.
 
 This guide is made for anyone who's interested in running LlamaIndex documentation locally,
 making changes to it and making contributions. LlamaIndex is made by the thriving community
@@ -14,31 +11,57 @@ documentation.
 
 If you haven't already, clone the LlamaIndex Github repo to a local directory:
 
-```bash
+```
 git clone https://github.com/run-llama/llama_index.git && cd llama_index
 ```
 
+Documentation has its own, dedicated Python virtual environment, and all the tools and scripts are available from the
+`docs` directory:
+
+```
+cd llama_index/docs
+```
+
+From now on, we assume all the commands will be executed from the `docs` directory.
+
 Install all dependencies required for building docs (mainly `mkdocs` and its extension):
 
 - [Install poetry](https://python-poetry.org/docs/#installation) - this will help you manage package dependencies
-- `poetry shell` - this command creates a virtual environment, which keeps installed packages contained to this project
-- `poetry install --only docs` - this will install all dependencies needed for building docs
+- `poetry install` - this will install all dependencies needed for building docs
+
+To build the docs and browse them locally run:
+
+```
+poetry run serve
+```
 
-Build with mkdocs:
+During the build, notebooks are converted to documentation pages, and this takes several minutes. If you're not
+working on the "Examples" section of the documentation, you can run the same command with `--skip-notebooks`:
 
-```bash
-cd docs
-mkdocs serve --dirty
+```
+poetry run serve --skip-notebooks
 ```
 
-**NOTE:** The `--dirty` option will mean that only changed files will be re-built, decreasing the time it takes to iterate on a page.
+> [!IMPORTANT]
+> Building the documentation takes a while, so make sure you see the following output before opening the browser:
+>
+> ```
+> ...
+> INFO    -  Documentation built in 53.32 seconds
+> INFO    -  [16:18:17] Watching paths for changes: 'docs'
+> INFO    -  [16:18:17] Serving on http://127.0.0.1:8000/en/stable/
+> ```
 
-And open your browser at http://localhost:8000/ to view the generated docs.
+You can now open your browser at http://localhost:8000/ to view the generated docs. The local server will rebuild the
+docs and refresh your browser every time you make changes to the docs.
 
-This hosted version will re-build and update as changes are made to the docs.
+## Configuration
 
-## Config
+Part of the configuration in `mkdocs.yml` is generated by a script that takes care of keeping the examples in sync as
+well as the API reference for all the packages in this repo.
 
-All config for mkdocs is in the `mkdocs.yml` file.
+Running the command `poetry run prepare-for-build` from the `docs` folder will update the `mkdocs.yml` with the latest
+changes, along with writing new api reference files.
 
-Running the command `python docs/prepare_for_build.py` from the root of the llama-index repo will update the mkdocs.yml API Reference and examples nav with the latest changes, as well as writing new api reference files.
+> [!TIP]
+> As a contributor, you wouldn't normally need to run this script, feel free to ask for help in the PR.

docs/docs/api_reference/embeddings/vertex_endpoint.md

@@ -0,0 +1,4 @@
+::: llama_index.embeddings.vertex_endpoint
+    options:
+      members:
+        - VertexEndpointEmbedding

docs/docs/api_reference/llama_deploy/README.txt

@@ -0,0 +1,2 @@
+Documentation content will be pulled from https://github.com/run-llama/llama_deploy,
+make sure to run `python docs/merge_llama_deploy_docs.py` before building docs.

docs/docs/api_reference/node_parser/docling.md

@@ -0,0 +1,4 @@
+::: llama_index.node_parser.docling
+    options:
+      members:
+        - DoclingNodeParser

docs/docs/api_reference/readers/docling.md

@@ -0,0 +1,4 @@
+::: llama_index.readers.docling
+    options:
+      members:
+        - DoclingReader

docs/docs/api_reference/storage/chat_store/azurecosmosnosql.md

@@ -0,0 +1,4 @@
+::: llama_index.storage.chat_store.azurecosmosnosql
+    options:
+      members:
+        - AzureCosmosNoSqlChatStore

docs/docs/api_reference/storage/index_store/azurecosmosnosql.md

@@ -0,0 +1,4 @@
+::: llama_index.storage.index_store.azurecosmosnosql
+    options:
+      members:
+        - AzureCosmosNoSqlIndexStore

docs/docs/api_reference/storage/kvstore/azurecosmosnosql.md

@@ -0,0 +1,4 @@
+::: llama_index.storage.kvstore.azurecosmosnosql
+    options:
+      members:
+        - AzureCosmosNoSqlKVStore

docs/docs/api_reference/storage/vector_store/objectbox.md

@@ -0,0 +1,4 @@
+::: llama_index.vector_stores.objectbox
+    options:
+      members:
+        - ObjectBoxVectorStore

docs/docs/module_guides/llama_deploy/README.txt

@@ -0,0 +1,2 @@
+Documentation content will be pulled from https://github.com/run-llama/llama_deploy,
+make sure to run `python docs/merge_llama_deploy_docs.py` before building docs.