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);