From 98a9e30edf233386b10f37263d6bebc78cf06fb9 Mon Sep 17 00:00:00 2001
From: Fabian Engelniederhammer <fabian.engelniederhammer@tngtech.com>
Date: Wed, 10 Jan 2024 13:09:42 +0100
Subject: [PATCH] feat(docs): separate maintainer docs from user docs #561

---
 lapis2-docs/astro.config.mjs                  | 45 ++++++++++---------
 .../references/configuration.mdx              | 26 +++++------
 .../tutorials}/start-lapis-and-silo.mdx       |  2 +-
 ...-global-distribution-of-sequences-in-r.mdx |  0
 lapis2-docs/tests/docs.spec.ts                | 28 +++++++++---
 5 files changed, 61 insertions(+), 40 deletions(-)
 rename lapis2-docs/src/content/docs/{ => maintainer-docs}/references/configuration.mdx (80%)
 rename lapis2-docs/src/content/docs/{tutorials/maintainer-tutorials => maintainer-docs/tutorials}/start-lapis-and-silo.mdx (98%)
 rename lapis2-docs/src/content/docs/tutorials/{user-tutorials => }/plot-global-distribution-of-sequences-in-r.mdx (100%)

diff --git a/lapis2-docs/astro.config.mjs b/lapis2-docs/astro.config.mjs
index 9f8e6586..29ef6c97 100644
--- a/lapis2-docs/astro.config.mjs
+++ b/lapis2-docs/astro.config.mjs
@@ -58,10 +58,6 @@ export default defineConfig({
                             label: 'Database Config',
                             link: '/references/database-config/',
                         },
-                        {
-                            label: 'Configuration',
-                            link: '/references/configuration/',
-                        },
                         {
                             label: 'Authentication',
                             link: '/references/authentication/',
@@ -103,22 +99,8 @@ export default defineConfig({
                     label: 'Tutorials',
                     items: [
                         {
-                            label: 'User tutorials',
-                            items: [
-                                {
-                                    label: 'Plot the global distribution of all sequences in R',
-                                    link: '/tutorials/user-tutorials/plot-global-distribution-of-sequences-in-r',
-                                },
-                            ],
-                        },
-                        {
-                            label: 'Maintainer tutorials',
-                            items: [
-                                {
-                                    label: 'Start LAPIS and SILO',
-                                    link: '/tutorials/maintainer-tutorials/start-lapis-and-silo',
-                                },
-                            ],
+                            label: 'Plot the global distribution of all sequences in R',
+                            link: '/tutorials/plot-global-distribution-of-sequences-in-r',
                         },
                     ],
                 },
@@ -155,6 +137,29 @@ export default defineConfig({
                         },
                     ],
                 },
+                {
+                    label: 'Maintainer Documentation',
+                    items: [
+                        {
+                            label: 'References',
+                            items: [
+                                {
+                                    label: 'Configuration',
+                                    link: '/maintainer-docs/references/configuration',
+                                },
+                            ],
+                        },
+                        {
+                            label: 'Tutorials',
+                            items: [
+                                {
+                                    label: 'Start LAPIS and SILO',
+                                    link: '/maintainer-docs/tutorials/start-lapis-and-silo',
+                                },
+                            ],
+                        },
+                    ],
+                },
             ],
         }),
         react(),
diff --git a/lapis2-docs/src/content/docs/references/configuration.mdx b/lapis2-docs/src/content/docs/maintainer-docs/references/configuration.mdx
similarity index 80%
rename from lapis2-docs/src/content/docs/references/configuration.mdx
rename to lapis2-docs/src/content/docs/maintainer-docs/references/configuration.mdx
index 3307e264..add754d5 100644
--- a/lapis2-docs/src/content/docs/references/configuration.mdx
+++ b/lapis2-docs/src/content/docs/maintainer-docs/references/configuration.mdx
@@ -3,15 +3,15 @@ title: Configuration
 description: Reference for how to configure LAPIS and SILO
 ---
 
-import { OnlyIf } from '../../../components/OnlyIf.tsx';
-import MetadataTypesList from '../../../components/Configuration/MetadataTypesList.astro';
-import { hasFeature } from '../../../config.ts';
+import { OnlyIf } from '../../../../components/OnlyIf.tsx';
+import MetadataTypesList from '../../../../components/Configuration/MetadataTypesList.astro';
+import { hasFeature } from '../../../../config.ts';
 
 # Database Configuration
 
 LAPIS and SILO need a `database_config.yaml`.
 It's main purpose is to define the database schema for the sequence metadata.
-See the [tutorial](/tutorials/maintainer-tutorials/start-lapis-and-silo#writing-configuration) for an example.
+See the [tutorial](/maintainer-docs/tutorials/start-lapis-and-silo#writing-configuration) for an example.
 More examples can be found in our tests.
 
 ## The Schema Object
@@ -20,10 +20,10 @@ The `database_config.yaml` must contain a `schema` object.
 It permits the following fields:
 
 | Key           | Type   | Required | Description                                                                                           |
-|---------------|--------|----------|-------------------------------------------------------------------------------------------------------|
+| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
 | instanceName  | string | true     | The name assigned to the instance. Only used for diplay purposes.                                     |
 | metadata      | array  | true     | A list of [metadata objects](#the-metadata-object) that is available on the underlying sequence data. |
-| opennessLevel | enum   | true     | `OPEN` or `PROTECTED`. See [authentication](./authentication).                                        |
+| opennessLevel | enum   | true     | `OPEN` or `PROTECTED`. See [authentication](/references/authentication).                              |
 | primaryKey    | string | true     | The field that serves as the primary key in SILO for the data.                                        |
 | dateToSortBy  | string | false    | The field used to sort the data by date. Queries on this column will be faster.                       |
 | partitionBy   | string | false    | The field used to partition the data. Used by SILO for overall query optimization.                    |
@@ -44,12 +44,12 @@ it will be beneficial to set `dateToSortBy` to that column.
 
 The metadata object permits the following fields:
 
-| Key             | Type    | Required | Description                                                                                                                  |
-|-----------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------|
-| name            | string  | true     | The name of the feature.                                                                                                     |
-| type            | enum    | true     | The [type of the metadata](#metadata-types).                                                                                 |
-| valuesAreUnique | boolean | false    | Whether this column uniquely identifies a row. Important when using the `PROTECTED` [authentication](./authentication) mode. |
-| generateIndex   | boolean | false    | Some [metadata types](#metadata-types) permit generating an index for faster queries on the column.                          |
+| Key             | Type    | Required | Description                                                                                                                            |
+| --------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| name            | string  | true     | The name of the feature.                                                                                                               |
+| type            | enum    | true     | The [type of the metadata](#metadata-types).                                                                                           |
+| valuesAreUnique | boolean | false    | Whether this column uniquely identifies a row. Important when using the `PROTECTED` [authentication](/references/authentication) mode. |
+| generateIndex   | boolean | false    | Some [metadata types](#metadata-types) permit generating an index for faster queries on the column.                                    |
 
 ### Metadata Types
 
@@ -77,4 +77,4 @@ The features object permits the following fields:
 Currently, there is only one available feature: `sarsCoV2VariantQuery`.
 This enables a specialized query language for SARS-CoV-2 instances.
 
-<OnlyIf condition={hasFeature('sarsCoV2VariantQuery')}>See [variant queries](../concepts/variant-query).</OnlyIf>
+<OnlyIf condition={hasFeature('sarsCoV2VariantQuery')}>See [variant queries](/concepts/variant-query).</OnlyIf>
diff --git a/lapis2-docs/src/content/docs/tutorials/maintainer-tutorials/start-lapis-and-silo.mdx b/lapis2-docs/src/content/docs/maintainer-docs/tutorials/start-lapis-and-silo.mdx
similarity index 98%
rename from lapis2-docs/src/content/docs/tutorials/maintainer-tutorials/start-lapis-and-silo.mdx
rename to lapis2-docs/src/content/docs/maintainer-docs/tutorials/start-lapis-and-silo.mdx
index b65d5e80..abe4dede 100644
--- a/lapis2-docs/src/content/docs/tutorials/maintainer-tutorials/start-lapis-and-silo.mdx
+++ b/lapis2-docs/src/content/docs/maintainer-docs/tutorials/start-lapis-and-silo.mdx
@@ -67,7 +67,7 @@ schema:
 ```
 
 :::tip
-See the [config reference](../../references/configuration) for a full specification.
+See the [config reference](/maintainer-docs/references/configuration) for a full specification.
 :::
 
 ### Starting SILO Preprocessing
diff --git a/lapis2-docs/src/content/docs/tutorials/user-tutorials/plot-global-distribution-of-sequences-in-r.mdx b/lapis2-docs/src/content/docs/tutorials/plot-global-distribution-of-sequences-in-r.mdx
similarity index 100%
rename from lapis2-docs/src/content/docs/tutorials/user-tutorials/plot-global-distribution-of-sequences-in-r.mdx
rename to lapis2-docs/src/content/docs/tutorials/plot-global-distribution-of-sequences-in-r.mdx
diff --git a/lapis2-docs/tests/docs.spec.ts b/lapis2-docs/tests/docs.spec.ts
index d6d46d42..304ef0c0 100644
--- a/lapis2-docs/tests/docs.spec.ts
+++ b/lapis2-docs/tests/docs.spec.ts
@@ -1,25 +1,30 @@
 import { expect, Page, test } from '@playwright/test';
 import { baseUrl } from './queryGenerator.page';
 
-const pages = [
-    'Introduction',
-    'Generate your request',
+const gettingStartedPages = ['Introduction', 'Generate your request'];
+
+const referencesPages = [
     'Introduction',
     'Fields',
     'Filters',
     'Open API / Swagger',
     'Reference Genome',
     'Database Config',
-    'Configuration',
     'Authentication',
+];
+
+const conceptsPages = [
     'Data versions',
     'Mutation filters',
     'Pango lineage query',
     'Request methods: GET and POST',
     'Response format',
     'Variant query',
-    'Plot the global distribution of all sequences in R',
-    'Start LAPIS and SILO',
+];
+
+const userTutorialPages = ['Plot the global distribution of all sequences in R'];
+
+const architecturePages = [
     'Introduction and Goals',
     'Architecture and Constraints',
     'System Scope and Context',
@@ -29,6 +34,17 @@ const pages = [
     'Glossary',
 ];
 
+const maintainerDocsPages = ['Configuration', 'Start LAPIS and SILO'];
+
+const pages = [
+    ...gettingStartedPages,
+    ...referencesPages,
+    ...conceptsPages,
+    ...userTutorialPages,
+    ...architecturePages,
+    ...maintainerDocsPages,
+];
+
 test.describe('The documentation', () => {
     test('should show all expected pages', async ({ page }) => {
         await page.goto(baseUrl);