From f8dccef258c06fa0f58d74fcb458556f29b6117c Mon Sep 17 00:00:00 2001 From: Mathieu Barbin Date: Fri, 20 Sep 2024 14:37:02 +0200 Subject: [PATCH] Update doc (diataxis) --- .../introduction.md => explanation/README.md} | 6 +++- doc/docs/{tests => explanation}/dune | 0 .../exploratory_tests.md | 0 doc/docs/{tests => explanation}/prelude.txt | 0 doc/docs/{design => explanation}/traits.md | 0 doc/docs/guides/README.md | 3 ++ doc/docs/{odoc => reference}/odoc.md | 0 doc/docs/tutorials/README.md | 3 ++ doc/docusaurus.config.ts | 36 ++++++++++++------- doc/sidebars.ts | 35 +++++++++++++----- 10 files changed, 60 insertions(+), 23 deletions(-) rename doc/docs/{design/introduction.md => explanation/README.md} (89%) rename doc/docs/{tests => explanation}/dune (100%) rename doc/docs/{tests => explanation}/exploratory_tests.md (100%) rename doc/docs/{tests => explanation}/prelude.txt (100%) rename doc/docs/{design => explanation}/traits.md (100%) create mode 100644 doc/docs/guides/README.md rename doc/docs/{odoc => reference}/odoc.md (100%) create mode 100644 doc/docs/tutorials/README.md diff --git a/doc/docs/design/introduction.md b/doc/docs/explanation/README.md similarity index 89% rename from doc/docs/design/introduction.md rename to doc/docs/explanation/README.md index 9c43885..a7ca2ed 100644 --- a/doc/docs/design/introduction.md +++ b/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. diff --git a/doc/docs/tests/dune b/doc/docs/explanation/dune similarity index 100% rename from doc/docs/tests/dune rename to doc/docs/explanation/dune diff --git a/doc/docs/tests/exploratory_tests.md b/doc/docs/explanation/exploratory_tests.md similarity index 100% rename from doc/docs/tests/exploratory_tests.md rename to doc/docs/explanation/exploratory_tests.md diff --git a/doc/docs/tests/prelude.txt b/doc/docs/explanation/prelude.txt similarity index 100% rename from doc/docs/tests/prelude.txt rename to doc/docs/explanation/prelude.txt diff --git a/doc/docs/design/traits.md b/doc/docs/explanation/traits.md similarity index 100% rename from doc/docs/design/traits.md rename to doc/docs/explanation/traits.md diff --git a/doc/docs/guides/README.md b/doc/docs/guides/README.md new file mode 100644 index 0000000..5c9d688 --- /dev/null +++ b/doc/docs/guides/README.md @@ -0,0 +1,3 @@ +# Introduction + +This part of the documentation is currently empty. diff --git a/doc/docs/odoc/odoc.md b/doc/docs/reference/odoc.md similarity index 100% rename from doc/docs/odoc/odoc.md rename to doc/docs/reference/odoc.md diff --git a/doc/docs/tutorials/README.md b/doc/docs/tutorials/README.md new file mode 100644 index 0000000..5c9d688 --- /dev/null +++ b/doc/docs/tutorials/README.md @@ -0,0 +1,3 @@ +# Introduction + +This part of the documentation is currently empty. diff --git a/doc/docusaurus.config.ts b/doc/docusaurus.config.ts index d57beb0..62a158d 100644 --- a/doc/docusaurus.config.ts +++ b/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/', }, ], }, diff --git a/doc/sidebars.ts b/doc/sidebars.ts index 0798671..5c6e0e6 100644 --- a/doc/sidebars.ts +++ b/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' }, ], }, ],