Update doc (diataxis)

doc/docs/design/introduction.md → doc/docs/explanation/README.md

@@ -1,4 +1,8 @@
-# Design principles
+# Explanation
+
+Welcome to the Explanation section of the `vcs` documentation. Here, we delve into the details of how `vcs` works, its design principles, and our future plans. This section is intended to provide a deeper understanding of the project for developers and contributors.
+
+## Design principles
 
 `Vcs` is designed to be backend-agnostic and concurrency-runtime independent. It's compatible with both `Eio` and OCaml `Stdlib` runtimes. We plan to explore the feasibility of supporting [luv](https://github.com/aantron/luv) and [miou](https://github.com/robur-coop/miou) runtimes as separate future work.
 

doc/docs/guides/README.md

@@ -0,0 +1,3 @@
+# Introduction
+
+This part of the documentation is currently empty.

doc/docs/tutorials/README.md

@@ -0,0 +1,3 @@
+# Introduction
+
+This part of the documentation is currently empty.

doc/docusaurus.config.ts

@@ -73,23 +73,29 @@ const config: Config = {
       items: [
         {
           type: 'docSidebar',
-          sidebarId: 'odocSidebar',
+          sidebarId: 'tutorialsSidebar',
           position: 'left',
-          label: 'OCaml Packages',
+          label: 'Tutorials',
         },
         {
           type: 'docSidebar',
-          sidebarId: 'designSidebar',
+          sidebarId: 'guidesSidebar',
           position: 'left',
-          label: 'Design',
+          label: 'Guides',
         },
         {
           type: 'docSidebar',
-          sidebarId: 'testsSidebar',
+          sidebarId: 'referenceSidebar',
           position: 'left',
-          label: 'Tests',
+          label: 'Reference',
         },
-        { to: '/blog/', label: 'Blog', position: 'left' },
+        {
+          type: 'docSidebar',
+          sidebarId: 'explanationSidebar',
+          position: 'left',
+          label: 'Explanation',
+        },
+        { to: '/blog/', label: 'Blog', position: 'right' },
         {
           href: 'https://github.com/mbarbin/vcs',
           label: 'GitHub',
@@ -110,16 +116,20 @@ const config: Config = {
           title: 'Docs',
           items: [
             {
-              label: 'OCaml Packages',
-              to: '/docs/odoc/',
+              label: 'Tutorials',
+              to: '/docs/tutorials/',
+            },
+            {
+              label: 'Guides',
+              to: '/docs/guides/',
             },
             {
-              label: 'Design',
-              to: '/docs/design/introduction/',
+              label: 'Reference',
+              to: '/docs/reference/odoc/',
             },
             {
-              label: 'Tests',
-              to: '/docs/tests/exploratory_tests/',
+              label: 'Explanation',
+              to: '/docs/explanation/',
             },
           ],
         },

doc/sidebars.ts

@@ -12,27 +12,44 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
 
-  odocSidebar: [
-    { type: 'doc', id: 'odoc/odoc', label: 'OCaml Packages' },
+  tutorialsSidebar: [
+    {
+      type: 'category',
+      label: 'Tutorials',
+      items: [
+        { type: 'doc', id: 'tutorials/README', label: 'Introduction' },
+      ],
+    },
+  ],
+
+  guidesSidebar: [
+    {
+      type: 'category',
+      label: 'Guides',
+      items: [
+        { type: 'doc', id: 'guides/README', label: 'Introduction' },
+      ],
+    },
   ],
 
-  designSidebar: [
+  referenceSidebar: [
     {
       type: 'category',
-      label: 'Design',
+      label: 'Reference',
       items: [
-        { type: 'doc', id: 'design/introduction', label: 'Introduction' },
-        { type: 'doc', id: 'design/traits', label: 'Traits' },
+        { type: 'doc', id: 'reference/odoc', label: 'OCaml Packages' },
       ],
     },
   ],
 
-  testsSidebar: [
+  explanationSidebar: [
     {
       type: 'category',
-      label: 'Tests',
+      label: 'Explanation',
       items: [
-        { type: 'doc', id: 'tests/exploratory_tests', label: 'Exploratory tests' },
+        { type: 'doc', id: 'explanation/README', label: 'Introduction' },
+        { type: 'doc', id: 'explanation/traits', label: 'Traits' },
+        { type: 'doc', id: 'explanation/exploratory_tests', label: 'Exploratory tests' },
       ],
     },
   ],