Merge pull request #7 from janhq/docs

docs: add redocusaurus

docs/README.md

@@ -39,3 +39,7 @@ $ GIT_USER=<Your GitHub username> 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.
+
+### Additional Plugins
+- @docusaurus/theme-live-codeblock
+- [Redocusaurus](https://redocusaurus.vercel.app/): manually upload swagger files at `/openapi/OpenAPISpec.json`

docs/docs/getting-started/README.md

@@ -1,7 +0,0 @@
----
-sidebar_position: 1
-slug: /
----
-
-# Getting Started
-Hi there

docs/docs/getting-started/README.mdx

@@ -0,0 +1,20 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Getting Started
+Hi there
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs groupId="operating-systems">
+  <TabItem value="win" label="Windows">Use Ctrl + C to copy.</TabItem>
+  <TabItem value="mac" label="macOS">Use Command + C to copy.</TabItem>
+</Tabs>
+
+<Tabs groupId="operating-systems">
+  <TabItem value="win" label="Windows">Use Ctrl + V to paste.</TabItem>
+  <TabItem value="mac" label="macOS">Use Command + V to paste.</TabItem>
+</Tabs>

docs/docs/reference/README.md

@@ -1,6 +0,0 @@
----
-sidebar_position: 1
----
-
-# Reference
-TODO

docs/docusaurus.config.js

@@ -32,6 +32,10 @@ const config = {
     locales: ['en'],
   },
 
+  // Plugins we added
+  // Only for react live
+  themes: ['@docusaurus/theme-live-codeblock'],
+
   // The classic preset will relay each option entry to the respective sub plugin/theme.
   presets: [
     [
@@ -43,11 +47,19 @@ const config = {
           routeBasePath: '/',
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl:
-            'https://github.com/janhq/jan/docs',
+            'https://github.com/janhq/jan/tree/main/docs',
           sidebarCollapsed: false,
           showLastUpdateAuthor: true,
           showLastUpdateTime: true,
         },
+        // Will be passed to @docusaurus/plugin-content-sitemap (false to disable)
+        sitemap: {
+          changefreq: 'weekly',
+          priority: 0.5,
+          ignorePatterns: ['/tags/**'],
+          filename: 'sitemap.xml',
+        },
+        // Will be passed to @docusaurus/plugin-content-blog (false to disable)
         blog: false,
         // Will be passed to @docusaurus/theme-classic.
         theme: {
@@ -57,14 +69,35 @@ const config = {
         // pages: {},
       }),
     ],
+    // Redoc preset
+    [
+      'redocusaurus',
+      {
+        specs: [
+          {
+            spec: 'openapi/OpenAPISpec.json', // can be local file, url, or parsed json object
+            route: '/reference/',
+          },
+        ],
+        theme: {
+          primaryColor: '#1a73e8',
+          primaryColorDark: '#1a73e8',
+          // redocOptions: { hideDownloadButton: false },
+        },
+      }
+    ]
   ],
 
   // Docs: https://docusaurus.io/docs/api/themes/configuration
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
-      // Replace with your project's social card
+      // TODO: Replace with your project's social card
       image: 'img/docusaurus-social-card.jpg',
+      // Only for react live
+      liveCodeBlock: {
+        playgroundPosition: 'bottom',
+      },
       navbar: {
         title: 'Jan Docs',
         logo: {
@@ -92,10 +125,9 @@ const config = {
             label: 'Developer',
           },
           {
-            type: 'docSidebar',
-            sidebarId: 'referenceSidebar',
             position: 'left',
             label: 'Reference',
+            to: '/reference',
           },
           {
             type: 'docSidebar',
@@ -103,15 +135,15 @@ const config = {
             position: 'left',
             label: 'Changelog',
           },
+          // Navbar right
           {
             type: 'docSidebar',
             sidebarId: 'aboutSidebar',
             position: 'right',
             label: 'About',
           },
-          // Navbar right
           {
-            href: 'https://github.com/janhq/jan/docs',
+            href: 'https://github.com/janhq/jan',
             label: 'GitHub',
             position: 'right',
           },
@@ -185,6 +217,7 @@ const config = {
       prism: {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
+        additionalLanguages: ['python'],
       },
     }),
 };

docs/openapi/OpenAPISpec.json

@@ -0,0 +1,74 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "description": "Jan.ai api reference documentation.",
+    "title": "Rest Endpoints",
+    "version": ""
+  },
+  "paths": {
+    "/api/rest/myquery": {
+      "get": {
+        "summary": "MyQuery",
+        "description": "***\nThe GraphQl query for this endpoint is:\n``` graphql\nquery MyQuery {\n  collections {\n    id\n    name\n    slug\n  }\n}\n```",
+        "parameters": [
+          {
+            "description": "Your x-hasura-admin-secret will be used for authentication of the API request.",
+            "in": "header",
+            "name": "x-hasura-admin-secret",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "collections": {
+                      "items": {
+                        "description": "columns and relationships of \"collections\"",
+                        "nullable": false,
+                        "properties": {
+                          "id": {
+                            "$ref": "#/components/schemas/uuid!"
+                          },
+                          "name": {
+                            "nullable": false,
+                            "title": "String",
+                            "type": "string"
+                          },
+                          "slug": {
+                            "nullable": false,
+                            "title": "String",
+                            "type": "string"
+                          }
+                        },
+                        "title": "collections",
+                        "type": "object"
+                      },
+                      "nullable": false,
+                      "type": "array"
+                    }
+                  }
+                }
+              }
+            },
+            "description": "Responses for GET /api/rest/myquery"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "uuid!": {
+        "nullable": false,
+        "pattern": "[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}",
+        "title": "uuid",
+        "type": "string"
+      }
+    }
+  }
+}

docs/package.json

@@ -16,11 +16,13 @@
   "dependencies": {
     "@docusaurus/core": "2.4.1",
     "@docusaurus/preset-classic": "2.4.1",
+    "@docusaurus/theme-live-codeblock": "^2.4.1",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react-dom": "^17.0.2",
+    "redocusaurus": "^1.6.3"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "2.4.1"

docs/sidebars.js

@@ -19,7 +19,6 @@ const sidebars = {
   }],
   guidesSidebar: [{ type: 'autogenerated', dirName: 'guides' }],
   developerSidebar: [{ type: 'autogenerated', dirName: 'developer' }],
-  referenceSidebar: [{ type: 'autogenerated', dirName: 'reference' }],
   changelogSidebar: [{ type: 'autogenerated', dirName: 'changelog' }],
   aboutSidebar: [{ type: 'autogenerated', dirName: 'about' }],