diff --git a/docs/README.md b/docs/README.md index b28211a9..436d7830 100644 --- a/docs/README.md +++ b/docs/README.md @@ -39,3 +39,39 @@ GIT_USER= yarn deploy ``` If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. + +## Update the OpenRAG documentation PDF + +The documentation PDF at `openrag/documents/openrag-documentation.pdf` is used by the OpenRAG application, so keep it up to date. + +To update the PDF, do the following: + +1. Remove elements from the `docs/*.mdx` files. +Content in tabs, details, and summary elements is hidden from PDF builds and it must be included. +To remove these items, give the following prompt or something similar to your IDE. + + ``` + Flatten documentation for PDF: remove tabs and details elements + In all MDX files in docs/docs/, flatten interactive elements: + Remove all and components: + Convert each tab's content to a regular section with an appropriate heading (### for subsections, ## for main sections) + Show all tab content sequentially + Remove the import statements for Tabs and TabItem where they're no longer used + Remove all
and elements: + Convert details content to regular text with an appropriate heading (### for subsections) + Show all content directly (no collapsible sections) + Keep all content visible — nothing should be hidden or collapsed + Maintain proper formatting and structure + Apply this to all documentation files that contain tabs or details elements so the content is fully flat and visible for PDF generation. + ``` + +2. Check your `.mdx` files to confirm these elements are removed. +Don't commit the changes. + +3. From `openrag/docs`, run this command to build the site with the changes, and create a PDF at `openrag/documents`. + + ``` + npm run build:pdf + ``` + +4. Check the PDF's content, then commit and create a pull request. \ No newline at end of file diff --git a/docs/docs/_partial-onboarding.mdx b/docs/docs/_partial-onboarding.mdx index 3f2de8fb..b8723d4c 100644 --- a/docs/docs/_partial-onboarding.mdx +++ b/docs/docs/_partial-onboarding.mdx @@ -7,7 +7,14 @@ The first time you start OpenRAG, whether using the TUI or a `.env` file, it's r To skip onboarding, click **Skip onboarding**. -Values from onboarding can be changed later in the OpenRAG **Settings** page. +:::warning +Most values from onboarding can be changed later in the OpenRAG **Settings** page, but there are important restrictions. + +The **language model provider** and **embeddings model provider** can only be selected at onboarding. +To change your provider selection later, you must [reinstall OpenRAG](/install#reinstall). + +You must use the same provider for your language model and embedding model, unless you're using Ollama. +::: Choose one LLM provider and complete only those steps: diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 94b7d22f..cbaa5095 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -98,7 +98,7 @@ If the TUI detects OAuth credentials, it enforces the **Advanced Setup** path. - **Basic Setup** generates all of the required values for OpenRAG except the OpenAI API key. + **Basic Setup** can generate all of the required values for OpenRAG except the OpenAI API key. **Basic Setup** does not set up OAuth connections for ingestion from cloud providers. For OAuth setup, use **Advanced Setup**. For information about the difference between basic (no auth) and OAuth in OpenRAG, see [Authentication and document access](/knowledge#auth). @@ -119,8 +119,9 @@ If the TUI detects OAuth credentials, it enforces the **Advanced Setup** path. Services started successfully Command completed successfully ``` - 6. To open the OpenRAG application, click **Open App**. - 7. Continue with [Application Onboarding](#application-onboarding). + 6. To start the Docling service, under **Native Services**, click **Start**. + 7. To open the OpenRAG application, click **Open App**. + 8. Continue with [Application Onboarding](#application-onboarding). @@ -145,7 +146,8 @@ If the TUI detects OAuth credentials, it enforces the **Advanced Setup** path. Services started successfully Command completed successfully ``` - 8. To open the OpenRAG application, click **Open App**. + 8. To start the Docling service, under **Native Services**, click **Start**. + 9. To open the OpenRAG application, click **Open App**. You are presented with your provider's OAuth sign-in screen. After sign-in, you are redirected to the redirect URI. @@ -160,7 +162,7 @@ If the TUI detects OAuth credentials, it enforces the **Advanced Setup** path. - OneDrive: `/connectors/onedrive/webhook` - SharePoint: `/connectors/sharepoint/webhook` - 9. Continue with [Application Onboarding](#application-onboarding). + 10. Continue with [Application Onboarding](#application-onboarding). @@ -228,4 +230,21 @@ To view the status, port, or PID of a native service, in the TUI main menu, clic ## Diagnostics -The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security. \ No newline at end of file +The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security. + +## Reinstall OpenRAG {#reinstall} + +To reinstall OpenRAG with a completely fresh setup: + +1. Reset your containers using the **Reset** button in the [TUI status](#status) menu. + This removes all containers, volumes, and data. + +2. Optional: Delete your project's `.env` file. + The Reset operation does not remove your project's `.env` file, so your passwords, API keys, and OAuth settings can be preserved. + If you delete the `.env` file, run the [Set up OpenRAG with the TUI](#setup) process again to create a new configuration. + +3. In the TUI Setup menu, follow these steps from [Basic Setup](#setup): + 1. Click **Start All Services** to pull container images and start them. + 2. Under **Native Services**, click **Start** to start the Docling service. + 3. Click **Open App** to open the OpenRAG application. + 4. Continue with [Application Onboarding](#application-onboarding). \ No newline at end of file diff --git a/docs/package.json b/docs/package.json index 095e3479..21b47600 100644 --- a/docs/package.json +++ b/docs/package.json @@ -6,7 +6,7 @@ "docusaurus": "docusaurus", "start": "docusaurus start", "build": "docusaurus build", - "build:pdf": "npm run build && npm run serve & sleep 10 && npx docusaurus-to-pdf && pkill -f 'docusaurus serve'", + "build:pdf": "rm -f ../documents/openrag-documentation.pdf && npm run build && npm run serve & sleep 10 && npx docusaurus-to-pdf && pkill -f 'docusaurus serve'", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", diff --git a/docs/pdf/openrag-documentation.pdf b/docs/pdf/openrag-documentation.pdf deleted file mode 100644 index 8009577b..00000000 Binary files a/docs/pdf/openrag-documentation.pdf and /dev/null differ diff --git a/docs/scraper.config.json b/docs/scraper.config.json index 94c57806..8a3d3daf 100644 --- a/docs/scraper.config.json +++ b/docs/scraper.config.json @@ -1,7 +1,7 @@ { "baseUrl": "http://localhost:3000", "entryPoint": "http://localhost:3000", - "outputDir": "./pdf/openrag-documentation.pdf", + "outputDir": "../documents/openrag-documentation.pdf", "customStyles": "table { max-width: 3500px !important; } .navbar, .footer, .breadcrumbs { display: none !important; }", "forceImages": true } \ No newline at end of file diff --git a/documents/openrag-documentation.pdf b/documents/openrag-documentation.pdf index cec6d2aa..48a06f72 100644 Binary files a/documents/openrag-documentation.pdf and b/documents/openrag-documentation.pdf differ