Refactor documentation architecture (#1264)

* Refactor documentation architecture Split into several `tab` and sections * Fix Fern's docs.yml after PR review Thank you Danny! Co-authored-by: dannysheridan <[email protected]> * Re-add quickstart in the overview tab It went missing after a refactoring of the doc architecture * Documentation writing * Adapt Makefile to fern documentation * Do not create overlapping page names in fern documentation This is causing 500. Thank you to @dsinghvi for the troubleshooting and the help! * Add a readme to help to understand how fern documentation work and how to add new pages * Rework the welcome view Redirects directly users to installation guide with links for people that are not familiar with documentation browsing. * Simplify the quickstart guide * PR feedback on installation guide A ton of refactoring can still be made there * PR feedback on ingestion * PR feedback on ingestion splitting * Rename section on LLM * Fix missing word in list of LLMs --------- Co-authored-by: dannysheridan <[email protected]>
zylon-ai · Nov 19, 2023 · 36f69ee · 36f69ee
1 parent 57a829a
commit 36f69ee
Show file tree

Hide file tree

Showing 18 changed files with 398 additions and 150 deletions.
diff --git a/Makefile b/Makefile
@@ -46,7 +46,7 @@ dev:
 ########################################################################################################################
 
 api-docs:
-	poetry run python scripts/extract_openapi.py private_gpt.main:app --out docs/openapi.json
+	PGPT_PROFILES=mock poetry run python scripts/extract_openapi.py private_gpt.main:app --out fern/openapi/openapi.json
 
 ingest:
 	@poetry run python scripts/ingest_folder.py $(call args)

diff --git a/fern/README.md b/fern/README.md
@@ -0,0 +1,39 @@
+# Documentation of privateGPT
+
+The documentation of this project is being rendered thanks to [fern](https://github.com/fern-api/fern).
+
+Fern is basically transforming your `.md` and `.mdx` files into a static website: your documentation.
+
+The configuration of your documentation is done in the `./docs.yml` file.
+There, you can configure the navbar, tabs, sections and pages being rendered.
+
+The documentation of fern (and the syntax of its configuration `docs.yml`) is 
+available there [docs.buildwithfern.com](https://docs.buildwithfern.com/).
+
+## How to run fern
+
+**You cannot render your documentation locally without fern credentials.**
+
+To see how your documentation looks like, you **have to** use the CICD of this
+repository (by opening a PR, CICD job will be executed, and a preview of 
+your PR's documentation will be deployed in vercel automatically, through fern).
+
+The only thing you can do locally, is to run `fern check`, which check the syntax of
+your `docs.yml` file.
+
+## How to add a new page
+Add in the `docs.yml` a new `page`, with the following syntax:
+
+```yml
+navigation:
+  # ...
+  - tab: my-existing-tab
+    layout:
+      # ...
+      - section: My Existing Section
+        contents:
+          # ...
+          - page: My new page display name
+            # The path of the page, relative to `fern/`
+            path: ./docs/pages/my-existing-tab/new-page-content.mdx
+```
diff --git a/fern/docs.yml b/fern/docs.yml
@@ -1,33 +1,92 @@
+# Main Fern configuration file
 instances:
   - url: privategpt.docs.buildwithfern.com
     custom-domain: docs.privategpt.dev
 
 title: PrivateGPT | Docs
 
+# The tabs definition, in the top left corner
+tabs:
+  overview:
+    display-name: Overview
+    icon: "fa-solid fa-home"
+  installation:
+    display-name: Installation
+    icon: "fa-solid fa-download"
+  manual:
+    display-name: Manual
+    icon: "fa-solid fa-book"
+  recipes:
+    display-name: Recipes
+    icon: "fa-solid fa-flask"
+  api-reference:
+    display-name: API Reference
+    icon: "fa-solid fa-file-contract"
+
+# Definition of tabs contents, will be displayed on the left side of the page, below all tabs
 navigation:
-  - section: Getting started
-    contents: 
-      - page: Welcome 
-        path: ./docs/pages/welcome.mdx
-      - page: Quickstart
-        path: ./docs/pages/quickstart.mdx
-      - page: Installation
-        path: ./docs/pages/installation.mdx
-      - page: LLMs
-        path: ./docs/pages/llms.mdx
-      - page: Vector Stores
-        path: ./docs/pages/vectordb.mdx
-  - section: Usage
-    contents:
-      - page: UI manual
-        path: ./docs/pages/ui.mdx
-      - page: Ingestion & Doc mgmt
-        path: ./docs/pages/ingestion.mdx
-      - page: SDKs
-        path: ./docs/pages/sdks.mdx
-  - api: API Reference
+  # The default tab
+  - tab: overview
+    layout:
+      - section: Welcome
+        contents:
+          - page: Welcome
+            path: ./docs/pages/overview/welcome.mdx
+          - page: Quickstart
+            path: ./docs/pages/overview/quickstart.mdx
+  # How to install privateGPT, with FAQ and troubleshooting
+  - tab: installation
+    layout:
+      - section: Getting started
+        contents:
+          - page: Installation
+            path: ./docs/pages/installation/installation.mdx
+  # Manual of privateGPT: how to use it and configure it
+  - tab: manual
+    layout:
+      - section: Document management
+        contents:
+          - page: Ingestion
+            path: ./docs/pages/manual/ingestion.mdx
+          - page: Deletion
+            path: ./docs/pages/manual/ingestion-reset.mdx
+      - section: Storage
+        contents:
+          - page: Vector Stores
+            path: ./docs/pages/manual/vectordb.mdx
+      - section: Advanced Setup
+        contents:
+          - page: LLM Backends
+            path: ./docs/pages/manual/llms.mdx
+      - section: User Interface
+        contents:
+          - page: User interface (Gradio) Manual
+            path: ./docs/pages/manual/ui.mdx
+  # Small code snippet or example of usage to help users
+  - tab: recipes
+    layout:
+      - section: Choice of LLM
+        contents:
+          # TODO: add recipes
+          - page: List of LLMs
+            path: ./docs/pages/recipes/list-llm.mdx
+  # More advanced usage of privateGPT, by API
+  - tab: api-reference
+    layout:
+      - section: Overview
+        contents:
+          - page : API Reference overview
+            path: ./docs/pages/api-reference/api-reference.mdx
+          - page: SDKs
+            path: ./docs/pages/api-reference/sdks.mdx
+      - api: API Reference
 
-navbar-links: 
+# Definition of the navbar, will be displayed in the top right corner.
+# `type:primary` is always displayed at the most right side of the navbar
+navbar-links:
+  - type: secondary
+    text: Github
+    url: "https://github.com/imartinez/privateGPT"
   - type: secondary
     text: Contact us
     url: "mailto:[email protected]"

diff --git a/fern/docs/pages/api-reference/api-reference.mdx b/fern/docs/pages/api-reference/api-reference.mdx
@@ -0,0 +1 @@
+# API Reference
diff --git a/fern/docs/pages/sdks.mdx → fern/docs/pages/api-reference/sdks.mdx b/fern/docs/pages/sdks.mdx → fern/docs/pages/api-reference/sdks.mdx
@@ -1,4 +1,6 @@
-We use [Fern](www.buildwithfern.com) to offer API clients for Node.js, Python, Go, and Java. We recommend using these clients to interact with our endpoints. The clients are kept up to date automatically, so we encourage you to use the latest version. 
+We use [Fern](www.buildwithfern.com) to offer API clients for Node.js, Python, Go, and Java.
+We recommend using these clients to interact with our endpoints.
+The clients are kept up to date automatically, so we encourage you to use the latest version.
 
 ## SDKs
 

diff --git a/fern/docs/pages/ingestion.mdx b/fern/docs/pages/ingestion.mdx
diff --git a/fern/docs/pages/installation.mdx → .../docs/pages/installation/installation.mdx b/fern/docs/pages/installation.mdx → .../docs/pages/installation/installation.mdx
@@ -9,9 +9,8 @@
   cd privateGPT
 ```
 
-* Install Python 3.11. Ideally through a python version manager like `pyenv`.
-  Python 3.12
-  should work too. Earlier python versions are not supported.
+* Install Python `3.11` (*if you do not have it already*). Ideally through a python version manager like `pyenv`.
+  Python 3.12 should work too. Earlier python versions are not supported.
     * osx/linux: [pyenv](https://github.com/pyenv/pyenv)
     * windows: [pyenv-win](https://github.com/pyenv-win/pyenv-win)
 
@@ -38,53 +37,17 @@ poetry install --with ui
 
 Verify everything is working by running `make run` (or `poetry run python -m private_gpt`) and navigate to
 http://localhost:8001. You should see a [Gradio UI](https://gradio.app/) **configured with a mock LLM** that will
-echo back the input. Later we'll see how to configure a real LLM.
+echo back the input. Below we'll see how to configure a real LLM.
 
 ### Settings
 
 <Callout intent="info">
-The default settings of PrivateGPT work out-of-the-box for a 100% local setup. Skip this section if you just want to test PrivateGPT locally, and come back later to learn about more configuration options.
+The default settings of PrivateGPT should work out-of-the-box for a 100% local setup. **However**, as is, it runs exclusively on your CPU.
+Skip this section if you just want to test PrivateGPT locally, and come back later to learn about more configuration options (and have better performances).
 </Callout>
 
 <br />
 
-PrivateGPT is configured through *profiles* that are defined using yaml files, and selected through env variables. The full list of properties configurable can be found in `settings.yaml`
-
-#### env var `PGPT_SETTINGS_FOLDER`
-
-The location of the settings folder. Defaults to the root of the project.
-Should contain the default `settings.yaml` and any other `settings-{profile}.yaml`.
-
-#### env var `PGPT_PROFILES`
-
-By default, the profile definition in `settings.yaml` is loaded.
-Using this env var you can load additional profiles; format is a comma separated list of profile names.
-This will merge `settings-{profile}.yaml` on top of the base settings file.
-
-For example:
-`PGPT_PROFILES=local,cuda` will load `settings-local.yaml`
-and `settings-cuda.yaml`, their contents will be merged with
-later profiles properties overriding values of earlier ones like `settings.yaml`.
-
-During testing, the `test` profile will be active along with the default, therefore `settings-test.yaml`
-file is required.
-
-#### Environment variables expansion
-
-Configuration files can contain environment variables,
-they will be expanded at runtime.
-
-Expansion must follow the pattern `${VARIABLE_NAME:default_value}`.
-
-For example, the following configuration will use the value of the `PORT`
-environment variable or `8001` if it's not set.
-Missing variables with no default will produce an error.
-
-```yaml
-server:
-  port: ${PORT:8001}
-```
-
 ### Local LLM requirements
 
 Install extra dependencies for local execution:
@@ -122,17 +85,33 @@ is used.
 
 #### Customizing low level parameters
 
-Currently not all the parameters of llama-cpp and llama-cpp-python are available at PrivateGPT's `settings.yaml` file. In case you need to customize parameters such as the number of layers loaded into the GPU, you might change these at the `llm_component.py` file under the `private_gpt/components/llm/llm_component.py`. If you are getting an out of memory error, you might also try a smaller model or stick to the proposed recommended models, instead of custom tuning the parameters.
+Currently, not all the parameters of `llama.cpp` and `llama-cpp-python` are available at PrivateGPT's `settings.yaml` file.
+In case you need to customize parameters such as the number of layers loaded into the GPU, you might change
+these at the `llm_component.py` file under the `private_gpt/components/llm/llm_component.py`.
+
+If you are getting an out of memory error, you might also try a smaller model or stick to the proposed
+recommended models, instead of custom tuning the parameters.
 
 #### OSX GPU support
 
-You will need to build [llama.cpp](https://github.com/ggerganov/llama.cpp) with
-metal support. To do that run:
+You will need to build [llama.cpp](https://github.com/ggerganov/llama.cpp) with metal support.
+
+To do that, you need to install `llama.cpp` python's binding `llama-cpp-python` through pip, with the compilation flag
+that activate `METAL`: you have to pass `-DLLAMA_METAL=on` to the CMake command tha `pip` runs for you (see below).
 
+In other words, one should simply run:
 ```bash
 CMAKE_ARGS="-DLLAMA_METAL=on" pip install --force-reinstall --no-cache-dir llama-cpp-python
 ```
 
+The above command will force the re-installation of `llama-cpp-python` with `METAL` support by compiling
+`llama.cpp` locally with your `METAL` libraries (shipped by default with your macOS).
+
+More information is available in the documentation of the libraries themselves:
+* [llama-cpp-python](https://github.com/abetlen/llama-cpp-python#installation-with-hardware-acceleration)
+* [llama-cpp-python's documentation](https://llama-cpp-python.readthedocs.io/en/latest/#installation-with-hardware-acceleration)
+* [llama.cpp](https://github.com/ggerganov/llama.cpp#build)
+
 #### Windows NVIDIA GPU support
 
 Windows GPU support is done through CUDA.
@@ -157,7 +136,7 @@ $env:CMAKE_ARGS='-DLLAMA_CUBLAS=on'; poetry run pip install --force-reinstall --
 If your installation was correct, you should see a message similar to the following next
 time you start the server `BLAS = 1`.
 
-```
+```console
 llama_new_context_with_model: total VRAM used: 4857.93 MB (model: 4095.05 MB, context: 762.87 MB)
 AVX = 1 | AVX2 = 1 | AVX512 = 0 | AVX512_VBMI = 0 | AVX512_VNNI = 0 | FMA = 1 | NEON = 0 | ARM_FMA = 0 | F16C = 1 | FP16_VA = 0 | WASM_SIMD = 0 | BLAS = 1 | SSE3 = 1 | SSSE3 = 0 | VSX = 0 |
 ```
@@ -194,7 +173,7 @@ llama_new_context_with_model: total VRAM used: 4857.93 MB (model: 4095.05 MB, co
 AVX = 1 | AVX2 = 1 | AVX512 = 0 | AVX512_VBMI = 0 | AVX512_VNNI = 0 | FMA = 1 | NEON = 0 | ARM_FMA = 0 | F16C = 1 | FP16_VA = 0 | WASM_SIMD = 0 | BLAS = 1 | SSE3 = 1 | SSSE3 = 0 | VSX = 0 |
 ```
 
-#### Known issues and Troubleshooting
+### Known issues and Troubleshooting
 
 Execution of LLMs locally still has a lot of sharp edges, specially when running on non Linux platforms.
 You might encounter several issues:
@@ -206,6 +185,11 @@ You might encounter several issues:
   Most likely you are missing some dev tools in your machine (updated C++ compiler, CUDA is not on PATH, etc.).
   If you encounter any of these issues, please open an issue and we'll try to help.
 
+One of the first reflex to adopt is: get more information.
+If, during your installation, something does not go as planned, retry in *verbose* mode, and see what goes wrong.
+
+For example, when installing packages with `pip install`, you can add the option `-vvv` to show the details of the installation.
+
 #### Troubleshooting: C++ Compiler
 
 If you encounter an error while building a wheel during the `pip install` process, you may need to install a C++
@@ -222,9 +206,10 @@ To install a C++ compiler on Windows 10/11, follow these steps:
 3. Download the MinGW installer from the [MinGW website](https://sourceforge.net/projects/mingw/).
 4. Run the installer and select the `gcc` component.
 
-** For OSX **
+**For OSX**
 
-1. Check if you have a C++ compiler installed, Xcode might have done it for you. for example running `gcc`.
+1. Check if you have a C++ compiler installed, `Xcode` should have done it for you. To install Xcode, go to the App
+   Store and search for Xcode and install it. **Or** you can install the command line tools by running `xcode-select --install`.
 2. If not, you can install clang or gcc with homebrew `brew install gcc`
 
 #### Troubleshooting: Mac Running Intel