docs: Set up documentation with MkDocs (DEV-4134) (#247)

Co-authored-by: Marcin Procyk <[email protected]>
Co-authored-by: Christian Kleinbölting <[email protected]>

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+# This workflow runs whenever a PR is opened or updated, or a commit is pushed to main. It runs
+# several checks:
+# - fmt: checks that the code is formatted according to rustfmt
+# - clippy: checks that the code does not contain any clippy warnings
+# - doc: checks that the code can be documented without errors
+# - hack: check combinations of feature flags
+# - msrv: check that the msrv specified in the crate is correct
+
+name: check
+
+permissions:
+  contents: read
+
+# This configuration allows maintainers of this repo to create a branch and pull request based on
+# the new branch. Restricting the push trigger to the main branch ensures that the PR only gets
+# built once.
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+# If new code is pushed to a PR branch, then cancel in progress workflows for that PR. Ensures that
+# we don't waste CI time, and returns results quicker https://github.com/jonhoo/rust-ci-conf/pull/5
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  markdownlint:
+      runs-on: ubuntu-latest
+      name: Check with markdownlint
+      steps:
+          - name: Checkout source
+            uses: actions/checkout@v4
+          - name: Install Just
+            uses: extractions/setup-just@v2
+          - name: Install requirements (pip, npm, apt)
+            run: |
+              just docs-install-requirements
+              npm install --global typedoc
+          - name: markdownlint
+            run: just markdownlint
+
+  build-docs:
+    runs-on: ubuntu-latest
+    name: Build Docs
+    steps:
+        - name: Checkout source
+          uses: actions/checkout@v4
+        - name: Install Just
+          uses: extractions/setup-just@v2
+        - name: Install requirements (pip, npm, apt)
+          run: |
+            just docs-install-requirements
+            npm install --global typedoc
+        - name: Build docs
+          run: just docs-build

.gitignore

@@ -11,3 +11,6 @@ web-frontend/.yarn/install-state.gz
 
 /target
 /.direnv
+
+# virtual environment for testing docs locally
+.venv

.markdownlint.yml

@@ -0,0 +1,41 @@
+# Config file for https://github.com/igorshubovych/markdownlint-cli
+
+# MD007/ul-indent - Unordered list indentation
+MD007: 
+    # Whether to indent the first level of the list
+    start_indented: false
+    # By how many spaces every next level must be indented. The default of 2 is not compatible with mkdocs!
+    indent: 4
+
+# MD009/no-trailing-spaces - Trailing spaces
+MD009: false
+
+# MD012/no-multiple-blanks - Multiple consecutive blank lines
+MD012: false
+
+# MD013/line-length - Line length
+MD013: 
+    line_length: 120
+    heading_line_length: 120
+    code_block_line_length: 120
+    # Include code blocks
+    code_blocks: true
+    # Include tables
+    tables: false
+    # Include headings
+    headings: true
+    headers: true
+    # Strict length checking
+    strict: false
+    # Stern length checking
+    stern: false
+
+# MD033/no-inline-html - Inline HTML
+MD033: 
+    allowed_elements: [br, center]
+
+# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
+MD041: false
+
+# MD045/no-alt-text - Images should have alternate text (alt text)
+MD045: false

docs/adding-metadata.md

@@ -0,0 +1,19 @@
+# Adding Metadata
+
+To add metadata to the [DSP-META repository](https://github.com/dasch-swiss/dsp-meta),
+simply add the metadata JSON file to the folder `data/json/` in the repository.
+
+The JSON file must conform to the schema of the metadata:
+
+- If the project is marked as "Ongoing", use the draft schema, found in `resources/schema-metadata-draft.json`.  
+  This schema is less strict and allows for incomplete metadata.
+- If the project is marked as "Finished", use the final schema, found in `resources/schema-metadata-final.json`.
+  This schema is strict and requires all fields to be filled out.
+
+Once the data is added, open a pull request to the repository. 
+The PR name must conform to the conventional commit format,
+using the prefix `data`.  
+E.g. `data: Add metadata for project XYZ`.
+
+To deploy the newly added metadata to the DSP Metadata Browser,
+a new release must be created and deployed to the server.