Skip to content

Commit

Permalink
feat(docs): separate maintainer docs from user docs #561
Browse files Browse the repository at this point in the history
  • Loading branch information
@fengelniederhammer
fengelniederhammer committed Jan 15, 2024
1 parent a1c21d9 commit 98a9e30
Show file tree
Hide file tree
Showing 5 changed files with 61 additions and 40 deletions.
45 changes: 25 additions & 20 deletions lapis2-docs/astro.config.mjs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,10 +58,6 @@ export default defineConfig({
label: 'Database Config',
link: '/references/database-config/',
},
{
label: 'Configuration',
link: '/references/configuration/',
},
{
label: 'Authentication',
link: '/references/authentication/',
Expand Down Expand Up @@ -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',
},
],
},
Expand Down Expand Up @@ -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(),
Expand Down
26 changes: 13 additions & 13 deletions ...content/docs/references/configuration.mdx → ...ntainer-docs/references/configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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. |
Expand All @@ -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

Expand Down Expand Up @@ -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>
2 changes: 1 addition & 1 deletion ...tainer-tutorials/start-lapis-and-silo.mdx → ...r-docs/tutorials/start-lapis-and-silo.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
0 ...global-distribution-of-sequences-in-r.mdx → ...global-distribution-of-sequences-in-r.mdx
View file
File renamed without changes.
28 changes: 22 additions & 6 deletions lapis2-docs/tests/docs.spec.ts
View file
Original file line number Diff line number Diff line change
@@ -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',
Expand All @@ -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);
Expand Down

0 comments on commit 98a9e30

Please sign in to comment.