chore: extend documentation (#924)

* chore: extend documentation * chore: move documentation to main README.md * chore: add eslint config to README.md * chore: change storybook link Co-authored-by: Max Schäfer <[email protected]> --------- Co-authored-by: Max Schäfer <[email protected]>
helpwave · Mar 12, 2024 · 38f8123 · 38f8123
1 parent 0ee9ebc
commit 38f8123
Show file tree

Hide file tree

Showing 5 changed files with 120 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -6,36 +6,51 @@ The official helpwave web frontends.
 
 ---
 
-## Projects 
+## [Projects](./documentation/structure.md) 
 This repository is split up into multiple subprojects using [pnpm](https://pnpm.io) workspaces.
 - helpwave tasks (see [tasks](/tasks))
-- Landing Page of helpwave (see [landing-page](/landing-page))
+- landing page of helpwave (see [landing-page](/landing-page))
+- library of helpwave (see [lib](/lib))
 
 ## Getting Started
-1. `pnpm install`
-2. `cd <project>`
-3. `pnpm run dev`
-4. open [`http://localhost:3000`](http://localhost:3000)
+To get started you will have to in install [pnpm](https://pnpm.io). After that you
+can use the following commands to start one of our projects.
+```shell
+pnpm install
+cd <project> # e.g. tasks, landing-page
+pnpm run dev
+```
+
+After that you should be able to open the project in the browser [`http://localhost:3000`](http://localhost:3000).
 
 ## Storybook
-`pnpm run storybook` in the lib folder
 
-We are about to adopting Storybook to develop, preview, testing and showcasing our components. Below you will find a listing of our deployed Storybook. You can also run these locally to develop new stories via the above command (open the displayed port in your browser of choice) in the supported projects.
+The components of our [library](lib) can be looked at in the storybook, where the different
+parameters of the component can be set individually.
+
+This allows you to see which components already exist and how to use them.
+The current version can be seen here https://components.helpwave.de.
 
-- [`lib` https://storybook-lib.helpwave.de](https://storybook-lib.helpwave.de)
+```shell
+cd lib
+pnpm run storybook
+```
 
 ## Testing
 This project is tested with [BrowserStack](https://www.browserstack.com).
 
 ## Linter
-1. `cd <project>`
-2. `pnpm run lint` or `pnpm run lint --fix`
+Our projects use linting with `eslint` to create a uniform code style. The linter can used with:
+
+```shell
+pnpm run --filter "@helpwave/*" lint
+```
 
-## Boilerplate generation
-The script lies in [scripts](/scripts)
+```shell
+pnpm run --filter "@helpwave/*" lint --fix
+```
 
-Execution with 
-- `node generate_boilerplate <relative filepath>`
-- `pnpm run generate <relative filepath>` (within the projects)
+It is configured in the [eslint-config](eslint-config/index.js).
 
-All options can be seen with the `--help` flag
+## [Scripts](documentation/scripts.md)
+The list of all our scripts can be found [here](documentation/scripts.md).
diff --git a/documentation/README.md b/documentation/README.md
@@ -0,0 +1,8 @@
+# Documentation
+
+This file will only give an overview of the different aspects of 
+our repository.
+
+- [Translation](./translation.md)
+- [Structure and pnpm](structure.md)
+- [Scripts](scripts.md)
diff --git a/documentation/scripts.md b/documentation/scripts.md
@@ -0,0 +1,13 @@
+# Scripts
+
+The full list of our scripts can be found here. All scripts are contained
+in the [scripts folder](../scripts)
+
+### Boilerplate generation
+This script is used to create the boilerplate for our components. Especially for the translations. 
+
+Execution with
+- `node generate_boilerplate <relative filepath>`
+- `pnpm run generate <relative filepath>` (within the projects)
+
+All options can be seen with the `--help` flag
diff --git a/documentation/structure.md b/documentation/structure.md
@@ -0,0 +1,12 @@
+# Structure
+The repository is structured as a mono repository managed with [pnpm](https://pnpm.io).
+All packages and apps we develop are within the main folder.
+
+### Applications 
+
+- [landing-page](../landing-page): The homepage of helpwave hosted on https://helpwave.de
+- [tasks](../tasks): The task management application for healthcare workers
+
+### Packages
+- [lib](../lib): The library containing all default components and additional utility functions for helpwave.
+For looking at the components refer to the [storybook](../README.md#storybook).
diff --git a/documentation/translation.md b/documentation/translation.md
@@ -0,0 +1,55 @@
+# Translation
+Translations are handled with three steps and per component.
+
+1. The type for the translation
+2. The default values for the translation
+3. The `useTranslation` hook
+
+Example:
+```tsx
+import { useTranslation } from '../../hooks/useTranslation'
+import type { PropsForTranslation } from '../../hooks/useTranslation'
+import type { Languages } from '../../hooks/useLanguage'
+
+type TitleTranslation = {
+  welcome: string,
+  goodToSeeYou: string,
+  page: (page: number) => string
+}
+
+const defaultTitleTranslations: Record<Languages, TitleTranslation> = {
+  en: {
+    welcome: 'Welcome',
+    goodToSeeYou: 'Good to see you',
+    page: (page) => `Page ${page}`
+  },
+  de: {
+    welcome: 'Willkommen',
+    goodToSeeYou: 'Schön dich zu sehen',
+    page: (page) => `Seite ${page}`
+  }
+}
+
+const Title = ({ overwriteTranslation, name }:PropsForTranslation<TitleTranslation, TitleProps>) => {
+  const translation = useTranslation(defaultTitleTranslations, overwriteTranslation)
+  return (
+    <p className={tw('rounded bg-gray-800 text-gray-200 p-1 px-2')}>
+      {translation.welcome}{'! '}
+      {translation.goodToSeeYou}{', '}
+      <span className={tw('text-green-300')}>{name}</span>{'. '}
+      {translation.page(123)}
+    </p>
+  )
+}
+```
+
+## Automatic Generation
+These components can be automatically generated with the following commands:
+
+```
+node generate_boilerplate <relative filepath>
+```
+or
+```
+pnpm run generate <relative filepath>
+```