Docs: various fixes + update mkdocs-material (docqai#172)

* docs: various improvements
  - build(docs): update mkdocs-material 8.5.11 -> 9.4.14
  - refactor: change accent colour to match marketing site (purple)
  - fix: various broken/missing links
  - fix: some content
  - add web API and agents holding pages
  - add Join Slack link

docs/acknowledgement.md

@@ -1,6 +1,11 @@
+# Acknowledgements
+
 The project would not have been possible without the following libraries:
 
 - [@jerryjliu](https://github.com/jerryjliu)'s [Llama Index](https://github.com/jerryjliu/llama_index)
+- [LiteLLM](https://github.com/BerriAI/litellm)
+- [Pydantic](https://github.com/pydantic/pydantic)
+- [OpenDAL](https://github.com/apache/incubator-opendal)
 - [Streamlit](https://streamlit.io/) and many open-source Streamlit components as well as its [Community Cloud](https://streamlit.io/cloud)
 
 This project was created using [cookiecutter](https://github.com/cookiecutter/cookiecutter) with:
@@ -11,5 +16,6 @@ Which includes a set of beautiful Python build toolings such as:
 
 - [Poetry](https://python-poetry.org/) and [Poe](https://poethepoet.natn.io/)
 - [Ruff](https://github.com/astral-sh/ruff)
+- [OpenTelemetry](https://github.com/open-telemetry)
 
 This docs site is created using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).

docs/developer-guide/getting-started.md

@@ -110,7 +110,7 @@ poe run-otel
 ### Build a docker image for tests
 
 ```sh
-poe docker-build --target test --build-tag 3.10-alpine --test true
+poe docker-build --target test --test true
 ```
 
 ```sh
@@ -130,13 +130,6 @@ poe docker-run --target test
   ```
 - TIP: Make sure `docker.env` is in the `.gitignore` file so it isn't checked in with secrets. It's also safer if you only have the environment variable name for secrets and set the value in your shell with `export`.
 
-### Build a container image with cached dependencies
-
-This is useful when iterating on the dockerfile itself
-
-  ```sh
-  poe docker-build-pipcached
-  ```
 
 ### Run container
 

docs/developer-guide/web-api.md

@@ -0,0 +1,5 @@
+# Web API (alpha)
+
+Coming soon...
+
+[Join our Slack](https://join.slack.com/t/docqai/shared_invite/zt-27p17lu6v-6KLJxSmt61vfNqCavSE73A) to discuss

docs/index.md

@@ -1,5 +1,7 @@
 # Introduction
 
+![Docq Illustration](./assets/docq-diag-nov2023.png)
+
 Docq helps your _**businesses**_ gain _**AI-based knowledge insight**_ from your _**private data, securely!**_
 
 Think of Docq as **your employees' private and secure ChatGPT, a second-brain that understands your business**.
@@ -15,4 +17,3 @@ For the developers and other tech-savvy audience, Docq is like **WordPress for g
 [User Guide](./user-guide/getting-started.md) - This is section is for _end-users_ (employees) and admins of the Docq app. It covers how to deploy and config Docq and how to use the AI chat funcitonality to help with your daily work.
 
 [Developer Guide](./developer-guide/getting-started.md) - This section id for those wanting to understand the Docq code base, make code changes to customise Docq, extend Docq, and use Docq as a platform to build AI powered applications on top.
-- [File Storage Services](./developer-guide/file-storage-services.md) - Docq supports multiple file storage services. This section covers how to setup the supported file storage services.

docs/overview/deployment-scenarios.md

@@ -13,6 +13,8 @@ Docq mainly caters for two deployment scenarios:
 
 Plus
 
+- **SaaS Multi-tenant** - An instance of Docq hosted and operated in our cloud provider account (Azure UK South region). Each organisations data is isolated but you are sharing a single instance of Docq and LLMs. This is the fast way to get going. Head over to [https://docq.ai/#plans](https://docq.ai/#plans) to subscribe.
+- **SaaS Dedicated** - Your own dedicated instance of Docq hosted and operated in our cloud account. You don't share any infrastructure with other organisations.
 - **On-Premise Deployment**: It is another option and we are happy to support you with a bespoke setup.
 
 Docq has been designed from ground up for the secure cloud and on-prem deployment scenarios with strict data security and privacy requirement in mind. However it should not stop all other businesses from adopting Docq with the flexible deployment setup if it suits their requirements.
@@ -26,7 +28,7 @@ The diagram above demonstrates the possibilities of have different deployment se
 
 ### Secure Cloud Deployment
 
-If your business have clear data security and privacy guideline, we recommend one of the big three cloud vendors:
+If your business have clear data security and privacy guidelines, we recommend one of the big three cloud vendors:
 
 - Microsoft Cloud (Azure)
 - Amazon Web Services (AWS)

docs/stylesheets/extra.css

@@ -2,14 +2,16 @@
   --md-primary-fg-color:        #202020;
   --md-primary-fg-color--light: #373737;
   --md-primary-fg-color--dark:  #373737;
-  --md-typeset-a-color: #4cae4f
+  --md-typeset-a-color: #542CF2;
+  //--md-typeset-a-color: #4cae4f;
 }
 
 [data-md-color-scheme="slate"] {
   --md-primary-fg-color:        #202020;
   --md-primary-fg-color--light: #373737;
   --md-primary-fg-color--dark:  #373737;
-  --md-typeset-a-color: #71c174
+  --md-typeset-a-color: #542CF2;
+  //--md-typeset-a-color: #71c174;
 }
 
 .mkapi-node code.mkapi-item-name, code.mkapi-object-parenthesis, code.mkapi-object-signature, span.mkapi-item-type, span.mkapi-item-dash, mkapi-item-description {

docs/user-guide/agents-actions.md

@@ -0,0 +1,5 @@
+# Agents and Actions
+
+Coming soon...
+
+[Join our Slack](https://join.slack.com/t/docqai/shared_invite/zt-27p17lu6v-6KLJxSmt61vfNqCavSE73A) to discuss.

docs/user-guide/configuration.md

@@ -1,3 +1,4 @@
 # Configuration
 
-- [Configure Spaces](./config-spaces.md)
+- [Configure Spaces](./config-spaces.md)
+- [Configure File Storage Services](./file-storage-services.md)

docs/developer-guide/file-storage-services.md → docs/user-guide/file-storage-services.md

@@ -2,14 +2,6 @@
 
 Docq supports multiple cloud file storage services as a data source. This section covers how to set up the supported file storage services.
 
-  - [Google Drive](#file-storage-google-drive)
-    - [Setup and Configure Google Cloud project](#setup-and-configure-google-cloud-project)
-    - [Configure Docq web application for Google Drive](#configure-docq-web-application-for-google-drive)
-  - [OneDrive](#file-storage-onedrive)
-    - [Setup and Configure Microsoft Azure Application](#setup-and-configure-microsoft-azure-application)
-    - [Configure Docq web application for OneDrive](#configure-docq-web-application-for-onedrive)
-
-
 ## File storage: Google Drive
 
 This guide aims to assist developers in integrating Google Drive with Docq. The focus will be on setting up the Google Drive API and obtaining the necessary credentials.
@@ -39,7 +31,6 @@ After setting up the Google Cloud project and configuring the Google Drive API,
 
 Note: The Google Drive data source will be automatically disabled if any of the above environment variables are not set.
 
-
 ## File storage: OneDrive
 
 This guide aims to assist developers in integrating OneDrive with Docq. The focus will be on setting up the Microsoft Graph API and obtaining the necessary credentials.
@@ -49,6 +40,7 @@ This guide aims to assist developers in integrating OneDrive with Docq. The focu
 - [Register an Application](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/isMSAApp~/false) in the Microsoft Entra ID center
 
 ![Register an Application](../assets/azure_register_an_application.png)
+
 - Configure the following under `Redirect URI`
   - Select `Web` as the platform
   - Enter the redirect URL to the following path `/Admin_Spaces/` e.g. `http://localhost:8501/Admin_Spaces/`

mkdocs.yaml

@@ -1,6 +1,6 @@
-site_name: Docq - Private & Secure AI Knowledge Insight
+site_name: Docq - Private & Secure ChatGPT AI Knowledge Insight
 site_url: https://docqai.github.io/docq
-site_description: Docq offers self-hosted, private and secure AI for knowledge insight on your private data with minimal onboarding and operational effort.
+site_description: Docq offers self-hosted, private and secure ChatGPT on your private data with minimal onboarding and operational effort.
 site_author: Docq Contributors
 copyright: Copyright © 2023 Docq Contributors
 site_dir: html
@@ -46,13 +46,13 @@ theme:
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: docq
-      accent: light-green
+      accent: purple
       toggle:
         icon: material/lightbulb-outline
         name: Switch to light mode
     - media: "(prefers-color-scheme: dark)"
       scheme: slate
-      accent: light-green
+      accent: purple
       toggle:
         icon: material/lightbulb
         name: Switch to dark mode
@@ -91,24 +91,27 @@ nav:
       - "Deployment Scenarios": overview/deployment-scenarios.md
   - "User Guides":
       - "Getting Started": user-guide/getting-started.md
+      - "Configuration": user-guide/configuration.md
       - "Deploy to Streamlit": user-guide/deploy-to-streamlit.md
-      - "Deploy to Azure": user-guide/deploy-to-streamlit.md
+      - "Deploy to Azure": user-guide/deploy-to-azure.md
       - "Deploy to AWS": user-guide/deploy-to-aws.md
       - "Deploy to GCP": user-guide/deploy-to-gcp.md
       - "Configure Spaces": user-guide/config-spaces.md
       - "Data Sources": user-guide/data-sources.md
+      - "Configure File Storage Services": user-guide/file-storage-services.md
       - "Usage": user-guide/usage.md
       - "FAQ": user-guide/faq.md
   - "Developer Guides":
       - "Getting Started": developer-guide/getting-started.md
       - "Architecture": developer-guide/architecture.md
       - "Contributing": developer-guide/contributing.md
       - "Extensions": developer-guide/extensions.md
+      - "Web API": developer-guide/web-api.md
       - "FAQ": developer-guide/faq.md
   #- ... | glob=readme.md
   #- ... | regex=scenarios/.+.md
-  - API: mkapi/api/docq
-  - Tests: mkapi/tests/tests
+  #- API: mkapi/api/docq
+  #- Tests: mkapi/tests/tests
   - "Issues GitHub": https://github.com/docqai/docq/issues
-  - "Discussions GitHub": https://github.com/docqai/docq/discussions
+  - "Join Our Slack": https://join.slack.com/t/docqai/shared_invite/zt-27p17lu6v-6KLJxSmt61vfNqCavSE73A
   - "Acknowledgement": acknowledgement.md

pyproject.toml

@@ -49,6 +49,7 @@ microsoftgraph-python = "^1.1.6"
 llama-index = "^0.9.8.post1"
 litellm = "^1.7.7"
 pydantic = "^2.5.2"
+mkdocs-material = "^9.4.14"
 
 [tool.poetry.group.dev.dependencies]
 pre-commit = "^2.18.1"
@@ -62,7 +63,7 @@ pytest-reverse = "^1.5.0"
 pytest-cov = "^3.0.0"
 pytest-bdd = "^6.1.1"
 mkdocs = "^1.4.2"
-mkdocs-material = "^8.5.10"
+mkdocs-material = "^9.4.14"
 mkdocs-gen-files = "^0.4.0"
 mkdocs-awesome-pages-plugin = "^2.8.0"
 mkapi = "^1.0.14"
@@ -194,23 +195,6 @@ args = [
     { name = "target", default = "prod" },
 ]
 
-[tool.poe.tasks.docker-build-pipcached]
-cmd = """
-docker build 
---build-arg TESTBUILD=$test \
---build-arg BUILDTAG=$build_tag \
---build-arg BUILDPLATFORM=$build_platform \
---build-arg PIPNOCACHE= \
---target $target \
--t docq:$target-$build_tag ."""
-help = "Build a docker image to test the project in an isolated environment"
-args = [
-    { name = "test", default = false, type = "boolean" },
-    { name = "build-tag", default = "3.11-slim-buster" },
-    { name = "build-platform", default = "linux/amd64" },
-    { name = "target", default = "prod" },
-]
-
 [tool.poe.tasks.docker-run]
 cmd = """
 docker run \