Rework documentation and link to SAD & other portal doc #68

Fix typos #68
bkd-mba-fbi · Jan 3, 2024 · 9416f1a · 9416f1a
1 parent dfab5bb
commit 9416f1a
Show file tree

Hide file tree

Showing 7 changed files with 116 additions and 121 deletions.
diff --git a/README.md b/README.md
@@ -6,58 +6,28 @@
 
 JavaScript web module to implement processes for school administration using the SLH.Evento backend (REST API).
 
-[Demo](https://bkd-mba-fbi.github.io/webapp-schulverwaltung/app)
+This project is realized with [Angular](https://angular.io/), [Bootstrap](https://getbootstrap.com/) and [io-ts](https://github.com/gcanti/io-ts). It is open source software, licensed under the terms of the [MIT license](./LICENSE).
 
-## Integration
+Download the [latest build](https://bkd-mba-fbi.github.io/webapp-schulverwaltung/webapp-schulverwaltung.zip) or checkout the [Demo](https://bkd-mba-fbi.github.io/webapp-schulverwaltung/app).
 
-Download the [latest build](https://bkd-mba-fbi.github.io/webapp-schulverwaltung/webapp-schulverwaltung.zip).
+## Documentation
 
-To integrate this application in your website, you have to copy and
-paste the import of the `settings.js` and the CSS files from
-`index.html`'s `<head>`:
+### Evento Portal
 
-```
-<head>
-  <script src="settings.js"></script>
-  <link rel="stylesheet" href="styles.xyz.css"></head>
-</head>
-```
+Although it can be used standalone during development, the _webapp-schulverwaltung_ is embedded in the [Evento Portal](https://github.com/bkd-mba-fbi/evento-portal) and developed by the same team, therefore the documentation of the _Evento Portal_ is relevant for this project to a large extent too, especially the following documents:
 
-In addition, you have to copy and paste the app tag and all `<script>`
-tags from `index.html`'s `<body>`:
+- [Software Architecture Documentation (SAD)](https://github.com/bkd-mba-fbi/evento-portal/blob/main/doc/sad.md)
+- [App Integration & API](https://github.com/bkd-mba-fbi/evento-portal/blob/main/doc/app-integration.md) – Providing of the OAuth tokens etc.
+- [Git Workflow](https://github.com/bkd-mba-fbi/evento-portal/blob/main/doc/git.md) – Branching (except the release branches) & commit messages
+- [Prettier](https://github.com/bkd-mba-fbi/evento-portal/blob/main/doc/prettier.md) – Source code formatting
 
-```
-<body>
-  <erz-app></erz-app>
-  <script type="text/javascript" src="runtime.xyz.js"></script>
-  ...
-  <script type="text/javascript" src="main.xyz.js"></script>
-</body>
-```
+### General
 
-To configure the app, you have to rename the file
-`settings.example.js` to `settings.js` and adjust its contents.
+- [Wiki](https://github.com/bkd-mba-fbi/webapp-schulverwaltung/wiki) – Common topics
 
-### Authorization
+### Development
 
-The website integrating this application has to make sure the OAuth
-access token is available in localStorage (or sessionStorage) under
-the key `CLX.LoginToken` (e.g. by setting
-`localStorage.setItem('CLX.LoginToken', '...')`). If not provided, the
-application displays a unauthenticated message to the user.
-
-### Important Notes
-
-- When integrated into the Evento Application, the App is wrapped in a
-  `<form>` tag. It is therefore important, that all `<button>`'s are
-  defined with `type="button"` attribute, otherwise the global form
-  will get submitted which results in a page reload.
-
-## Development
-
-- Common aspects are documented in the [Wiki](https://github.com/bkd-mba-fbi/webapp-schulverwaltung/wiki)
-- [Setup development environment](doc/setup-dev-environment.md)
-- [Prettier](doc/prettier.md)
-- [Browser support](doc/browser-support.md)
-- [Internationalization (i18n)](doc/i18n.md)
-- [API Data Contract (Data Decoding)](doc/io-ts.md)
+- [Setup & Development](doc/development.md) – Start local development, run linting & tests
+- [Internationalization (i18n)](doc/i18n.md) – Translating texts
+- [Browser Testing](doc/browser-testing.md) – Support & BrowserStack.com
+- [Data Decoding with io-ts](doc/io-ts.md) – API data contract
diff --git a/doc/browser-support.md → doc/browser-testing.md b/doc/browser-support.md → doc/browser-testing.md
@@ -1,10 +1,14 @@
-# Browser support
-
 [back](../README.md)
 
+# Browser Testing
+
+## Requirements
+
 We support the evergreen browsers (Chrome, Firefox, Safari, Edge).
 
-## Testing with BrowserStack
+## BrowserStack.com
+
+### Live Testing
 
 When testing browser compatibility with [BrowserStack](https://www.browserstack.com/), consider the following combination of Dev Server and URL to use.
 
@@ -14,4 +18,6 @@ When testing browser compatibility with [BrowserStack](https://www.browserstack.
 | Android   | Chrome                | `npm start`                  | `http://localhost:4200`    |
 | macOS/iOS | Safari                | `npm run start:browserstack` | `http://bs-local.com:8000` |
 
+### Authentication
+
 With all browsers you must store a valid token in localStorage to be able to use the app.
diff --git a/doc/development.md b/doc/development.md
@@ -0,0 +1,86 @@
+[back](../README.md)
+
+# Setup & Development
+
+This project was generated with [Angular CLI](https://github.com/angular/angular-cli).
+
+## Getting Started
+
+Preparation:
+
+- Install Node.js (preferably using [NVM](https://github.com/creationix/nvm)).
+- Clone this repository.
+- Execute `nvm use` to enable the correct Node version.
+- Execute `npm install` to install the dependencies.
+- Copy [src/settings.example.js](../src/settings.example.js) to `src/settings.js` and adjust its contents.
+- You're good to go 🚀
+
+Start the development server:
+
+```
+npm start
+```
+
+The application is then running on http://localhost:4200.
+
+To be able to make authenticated requests to the API, the OAuth access token has to be available in localStorage (or sessionStorage) under the key `CLX.LoginToken` (by setting `localStorage.setItem("CLX.LoginToken", "ey...")`). If not provided, the application displays an unauthenticated message to the user.
+
+## Code scaffolding
+
+Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
+
+## Build
+
+Build the project:
+
+```
+npm run build
+```
+
+Or for a production build:
+
+```
+npm run build:prod
+```
+
+The build artifacts will be stored in the `dist/` directory.
+
+If you have cloned the [event-portal](https://github.com/bkd-mba-fbi/evento-portal/) repository to `../evento-portal` relative to this repository (i.e. into the same directory), you can run the following to build and copy the application to the _Evento Portal_ for testing it integrated:
+
+```
+npm run build-and-copy-local
+```
+
+Visualize the contents of the generated bundle by running:
+
+```
+npm run analyze
+```
+
+## Linting & Testing
+
+### Linting & Checks
+
+Check source files with [ESLint](https://eslint.org/) (for the configuration, see [.eslintrc.json](./.eslintrc.json)):
+
+```
+npm run lint
+```
+
+Print a report of unused dependencies, files & exports using [Knip](https://github.com/webpro/knip) (for the configuration, see [.knip.json](../.knip.json)):
+
+```
+npm run unused
+```
+
+### Unit tests
+
+Execute the unit tests via [Karma](https://karma-runner.github.io):
+
+```
+npm test
+```
+
+## Further help
+
+To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md).
diff --git a/doc/i18n.md b/doc/i18n.md
@@ -1,7 +1,7 @@
-# Internationalization (i18n)
-
 [back](../README.md)
 
+# Internationalization (i18n)
+
 ## Language selection
 
 To select the language, the following properties are taken into account (in the given order):
@@ -18,4 +18,4 @@ https://github.com/ngx-translate/core#4-use-the-service-the-pipe-or-the-directiv
 
 ## Edit translations
 
-The translations are stored in JSON fomat and can be found in `src/assets/locales/*.json`.
+The translations are stored in JSON format and can be found in `src/assets/locales/*.json`.
diff --git a/doc/io-ts.md b/doc/io-ts.md
@@ -1,7 +1,7 @@
-# API Data Contract (Data Decoding)
-
 [back](../README.md)
 
+# Data Decoding with io-ts
+
 ## Introduction
 
 Since the backend of this application is developed and operated by a

diff --git a/doc/prettier.md b/doc/prettier.md
diff --git a/doc/setup-dev-environment.md b/doc/setup-dev-environment.md