build(docs): build docs with mkdocs (#37)

This PR introduces building Nesis documentation with mkdocs. Closes #32
ametnes · Apr 21, 2024 · 275abf9 · 275abf9
1 parent 5099ffb
commit 275abf9
Show file tree

Hide file tree

Showing 16 changed files with 2,035 additions and 5 deletions.
diff --git a/.github/workflows/jekyll-gh-pages.yml → .github/workflows/documentation.yml b/.github/workflows/jekyll-gh-pages.yml → .github/workflows/documentation.yml
@@ -1,5 +1,5 @@
 # Sample workflow for building and deploying a Jekyll site to GitHub Pages
-name: Deploy Jekyll with GitHub Pages dependencies preinstalled
+name: Build and Deploy Documentation
 
 on:
   # Runs on pushes targeting the default branch
@@ -30,11 +30,17 @@ jobs:
         uses: actions/checkout@v4
       - name: Setup Pages
         uses: actions/configure-pages@v5
-      - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@v1
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          source: ./
-          destination: ./_site
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-docs.txt
+      - name: Build with MkDocs
+        run: |
+          mkdocs build --clean --config-file docs/mkdocs.yml --site-dir ../_site
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
 

diff --git a/.gitignore b/.gitignore
@@ -144,3 +144,5 @@ dist
 videos
 screenshots
 #*.mp4
+
+site
diff --git a/compose.yml b/compose.yml
@@ -25,6 +25,7 @@ services:
     environment:
       NESIS_API_PORT: "6000"
       NESIS_API_DATABASE_URL: "postgresql://postgres:password@database:5432/nesis"
+      NESIS_API_TASKS_JOB_STORES_URL: "postgresql://postgres:password@database:5432/nesis"
       NESIS_ADMIN_EMAIL: "some.email@domain.com"
       NESIS_ADMIN_PASSWORD: "password"
       NESIS_MEMCACHE_HOSTS: memcached:11211
@@ -42,6 +43,7 @@ services:
     environment:
       NESIS_RAG_SERVER_PORT: "8080"
       NESIS_RAG_PGVECTOR_URL: postgresql://postgres:password@database:5432/nesis
+      HF_TOKEN: <your-huggingface-token>
       # 1. local mode uses hugging face. Other options
       NESIS_RAG_EMBEDDING_MODE: local
       NESIS_RAG_EMBEDDING_DIMENSIONS: "384"

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -0,0 +1,41 @@
+site_name: Nesis - AI Powered Enterprise Knowledge Partner
+site_description: Your AI Powered Enterprise Knowledge Partner
+site_url: https://ametnes.github.io/nesis/
+repo_url: https://github.com/ametnes/nesis/
+docs_dir: 'src'
+theme:
+  name: material
+  logo: 'images/NesisIcon.png'
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      media: "(prefers-color-scheme: light)"
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      media: "(prefers-color-scheme: dark)"
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - content.code.copy
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+
+nav:
+  - Home: 'index.md'
+  - 'Quick Start': 'quick-start.md'
+  - 'Development Guide':
+      - 'Local Development': 'dev-guide/local.md'
+      - 'Architecture': 'dev-guide/architecture.md'
+      - 'Contributing': 'dev-guide/contributing.md'
+extra_css:
+    - css/extra.css
+extra_javascript:
+  - scripts/menus.js
diff --git a/docs/src/css/_color.css b/docs/src/css/_color.css
@@ -0,0 +1,148 @@
+////
+/// Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+///
+/// Permission is hereby granted, free of charge, to any person obtaining a
+/// copy of this software and associated documentation files (the "Software"),
+/// to deal in the Software without restriction, including without limitation
+/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+/// and/or sell copies of the Software, and to permit persons to whom the
+/// Software is furnished to do so, subject to the following conditions:
+///
+/// The above copyright notice and this permission notice shall be included in
+/// all copies or substantial portions of the Software.
+///
+/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
+/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+/// DEALINGS
+////
+
+// ----------------------------------------------------------------------------
+// Rules
+// ----------------------------------------------------------------------------
+
+// Color variables
+:root {
+  @extend %root;
+
+  // Primary color shades
+  --md-primary-fg-color:               hsla(#{hex2hsl($clr-indigo-500)}, 1);
+  --md-primary-fg-color--light:        hsla(#{hex2hsl($clr-indigo-400)}, 1);
+  --md-primary-fg-color--dark:         hsla(#{hex2hsl($clr-indigo-700)}, 1);
+  --md-primary-bg-color:               hsla(0, 0%, 100%, 1);
+  --md-primary-bg-color--light:        hsla(0, 0%, 100%, 0.7);
+
+  // Accent color shades
+  --md-accent-fg-color:                hsla(#{hex2hsl($clr-indigo-a200)}, 1);
+  --md-accent-fg-color--transparent:   hsla(#{hex2hsl($clr-indigo-a200)}, 0.1);
+  --md-accent-bg-color:                hsla(0, 0%, 100%, 1);
+  --md-accent-bg-color--light:         hsla(0, 0%, 100%, 0.7);
+}
+
+// ----------------------------------------------------------------------------
+
+// Allow to explicitly use color schemes in nested content
+[data-md-color-scheme="default"] {
+  @extend %root;
+
+  // Indicate that the site is rendered with a light color scheme
+  color-scheme: light;
+
+  // Hide images for dark mode
+  img[src$="#only-dark"],
+  img[src$="#gh-dark-mode-only"] {
+    display: none;
+  }
+}
+
+// ----------------------------------------------------------------------------
+// Placeholders
+// ----------------------------------------------------------------------------
+
+// Default theme, i.e. light mode
+%root {
+
+  // Default color shades
+  --md-default-fg-color:               hsla(0, 0%, 0%, 0.87);
+  --md-default-fg-color--light:        hsla(0, 0%, 0%, 0.54);
+  --md-default-fg-color--lighter:      hsla(0, 0%, 0%, 0.32);
+  --md-default-fg-color--lightest:     hsla(0, 0%, 0%, 0.07);
+  --md-default-bg-color:               hsla(0, 0%, 100%, 1);
+  --md-default-bg-color--light:        hsla(0, 0%, 100%, 0.7);
+  --md-default-bg-color--lighter:      hsla(0, 0%, 100%, 0.3);
+  --md-default-bg-color--lightest:     hsla(0, 0%, 100%, 0.12);
+
+  // Code color shades
+  --md-code-fg-color:                  hsla(200, 18%, 26%, 1);
+  --md-code-bg-color:                  hsla(0, 0%, 96%, 1);
+
+  // Code highlighting color shades
+  --md-code-hl-color:                  hsla(#{hex2hsl($clr-yellow-a200)}, 0.5);
+  --md-code-hl-number-color:           hsla(0, 67%, 50%, 1);
+  --md-code-hl-special-color:          hsla(340, 83%, 47%, 1);
+  --md-code-hl-function-color:         hsla(291, 45%, 50%, 1);
+  --md-code-hl-constant-color:         hsla(250, 63%, 60%, 1);
+  --md-code-hl-keyword-color:          hsla(219, 54%, 51%, 1);
+  --md-code-hl-string-color:           hsla(150, 63%, 30%, 1);
+  --md-code-hl-name-color:             var(--md-code-fg-color);
+  --md-code-hl-operator-color:         var(--md-default-fg-color--light);
+  --md-code-hl-punctuation-color:      var(--md-default-fg-color--light);
+  --md-code-hl-comment-color:          var(--md-default-fg-color--light);
+  --md-code-hl-generic-color:          var(--md-default-fg-color--light);
+  --md-code-hl-variable-color:         var(--md-default-fg-color--light);
+
+  // Typeset color shades
+  --md-typeset-color:                  var(--md-default-fg-color);
+
+  // Typeset `a` color shades
+  --md-typeset-a-color:                var(--md-primary-fg-color);
+
+  // Typeset `mark` color shades
+  --md-typeset-mark-color:             hsla(#{hex2hsl($clr-yellow-a200)}, 0.5);
+
+  // Typeset `del` and `ins` color shades
+  --md-typeset-del-color:              hsla(6, 90%, 60%, 0.15);
+  --md-typeset-ins-color:              hsla(150, 90%, 44%, 0.15);
+
+  // Typeset `kbd` color shades
+  --md-typeset-kbd-color:              hsla(0, 0%, 98%, 1);
+  --md-typeset-kbd-accent-color:       hsla(0, 100%, 100%, 1);
+  --md-typeset-kbd-border-color:       hsla(0, 0%, 72%, 1);
+
+  // Typeset `table` color shades
+  --md-typeset-table-color:            hsla(0, 0%, 0%, 0.12);
+  --md-typeset-table-color--light:     hsla(0, 0%, 0%, 0.035);
+
+  // Admonition color shades
+  --md-admonition-fg-color:            var(--md-default-fg-color);
+  --md-admonition-bg-color:            var(--md-default-bg-color);
+
+  // Warning color shades
+  --md-warning-fg-color:              hsla(0, 0%, 0%, 0.87);
+  --md-warning-bg-color:              hsla(60, 100%, 80%, 1);
+
+  // Footer color shades
+  --md-footer-fg-color:                hsla(0, 0%, 100%, 1);
+  --md-footer-fg-color--light:         hsla(0, 0%, 100%, 0.7);
+  --md-footer-fg-color--lighter:       hsla(0, 0%, 100%, 0.45);
+  --md-footer-bg-color:                hsla(0, 0%, 0%, 0.87);
+  --md-footer-bg-color--dark:          hsla(0, 0%, 0%, 0.32);
+
+  // Shadow depth 1
+  --md-shadow-z1:
+    0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.05),
+    0 0              #{px2rem(1px)}  hsla(0, 0%, 0%, 0.1);
+
+  // Shadow depth 2
+  --md-shadow-z2:
+    0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.1),
+    0 0              #{px2rem(1px)}  hsla(0, 0%, 0%, 0.25);
+
+  // Shadow depth 3
+  --md-shadow-z3:
+    0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.2),
+    0 0              #{px2rem(1px)}  hsla(0, 0%, 0%, 0.35);
+}
diff --git a/docs/src/css/extra.css b/docs/src/css/extra.css
@@ -0,0 +1,18 @@
+/* Maximum space for text block */
+.md-grid {
+  max-width: 90%;
+}
+
+/*https://github.com/squidfunk/mkdocs-material/issues/175#issuecomment-616694465*/
+.md-typeset__table {
+   min-width: 100%;
+}
+.md-typeset table:not([class]) {
+    display: table;
+}
+
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3 {
+  color: #04A9F4;
+}
diff --git a/docs/src/deployment.md b/docs/src/deployment.md
diff --git a/docs/src/dev-guide/architecture.md b/docs/src/dev-guide/architecture.md
@@ -0,0 +1,25 @@
+# Nesis Architecture
+The Nessus project is divided into three components.
+
+1. Frontend - This contains the ReactJS frontend and Node Express server (aka frontend-backend)
+2. API Backend - This is the backend API responsible for handling 
+       1. Authentication
+       2. User management
+       3. Enforcing Role based access control
+       4. Process scheduling
+       5. And more
+6. RAG Engine - This is response for
+       7. Converting documents into embeddings
+       8. Interfacing with any OpenAI compatible endpoints
+
+## RAG Engine
+### Vector Database
+### Local Embeddings
+### OpenAI Embeddings
+### LLM
+
+## Backend API
+TODO
+
+## Frontend
+TODO
diff --git a/docs/src/dev-guide/contributing.md b/docs/src/dev-guide/contributing.md
@@ -0,0 +1,17 @@
+# Contribution Guide
+
+## Coding Style
+TODO
+
+## Testing
+TODO
+
+## Submitting your changes
+TODO
+
+### PR Titles
+TODO
+
+### Merging your PR
+TODO
+