Updated documentation

.gitignore

@@ -196,3 +196,5 @@ config.dev.ts
 # Ignore songs (we don't want them in tree)
 pages/songbook/songs
 pages/songbook/songs.json
+
+build

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "extern/ts-extractor-singlefile-modules"]
+	path = extern/ts-extractor-singlefile-modules
+	url = [email protected]:jonasKjellerup/ts-extractor-singlefile-modules.git

README.md

@@ -1,20 +1,40 @@
 
-# F-Appen
+# Fappen
 
-F-Appen is an app that strives to connect the various F-Klub services/systems in a single mobile package.
+Fappen is an app that strives to connect the various F-Klub services/systems in a single mobile package.
 
 ## Project Environment  
 
 To set up a development environment for the project you will need the following setup on your system:  
 
  - Node.JS (Any semi recent version should work - has been tested to work with V17)  
- - A local [stregsystem](https://github.com/f-klubben/stregsystemet) setup. Since the app depends on the API you will need with that implemented (see [stregsystem/#320](https://github.com/f-klubben/stregsystemet/pull/320)).  
+ - A local [stregsystem](https://github.com/f-klubben/stregsystemet) setup. Since the app depends on the API you will need a vesion with that implemented (see [stregsystem/#320](https://github.com/f-klubben/stregsystemet/pull/320)).  
 
 Running the project:  
 
 ```bash  
-npm install     # Installs dependencies  
+npm i --force   # Installs dependencies  
 npm start       # Builds the project and starts a local server  
 ```  
 
 To just build the project run `npm run build`.
+
+## Generating documentation
+
+For more information on building and developing the project build and read the documentation.
+This can be done as follows:
+
+```bash
+git submodule init
+git submodule update
+
+npm run setup-doc-extractor
+npm i --force
+
+# this last command is only needed if you have previous run `npm i`
+npm run reload-doc-extractor
+```
+
+Some parts of the documentation can also be accessed without building it by navigating to the
+`docs/Guides` folder on the GitHub website or in a markdown reader
+(although they are not guaranteed to render correctly).

docs/Guides/project_structure.md

@@ -0,0 +1,53 @@
+---
+name: Project structure
+---
+
+# Project structure
+
+The project is built around using the Parcel web bundler as a sort of static site generator. In general, we strive
+to do as much of the work statically as possible, in order to reduce the amount of client side code that we introduce.
+Obviously some components such as the stregsystem component are inherently tied to dynamic information and as such
+makes heavy use of runtime page rendering.
+
+A key thing to note about the project is that it does not consist of a server component (and never will). Things are
+either done statically or on the client side.
+
+Overview of the project repository structure.
+
+```
+# Utility and other
+/.github        # GitHub actions
+/util           # Various utility/helper scripts
+/extern         # External projects
+/docs           # Documentation files
+
+# Core application
+/components     # Resuseable components for the frontend
+/media          # Other static assets for the web app (mainly images)
+/pages          # The actual pages that make up the app
+/scripts        # Scripts that implement the appication logic
+/styles         # SCSS styles for the app pages/components
+```
+
+## Project root (`/`)
+
+The project is reserved mainly for configuration files for the various tools that we use.
+
+
+## Pages (`/pages`)
+
+The pages directory contains the pug templates from which the HTML pages for the application are generated.
+Note that the structure of this directory is directly reflected in the url of the web app, this should
+be kept in mind when adding files to the directory.
+
+## Utility (`/util`)
+
+This is a folder that is used for a bit of everything. Currently, primarily used for build scripts of various types,
+but may be used for anything that is not part of the core application logic.
+
+## External projects (`/extern`)
+
+External projects are dependencies that are especially tedious to include in the typical manner (read NPM).
+One such example is the documentation extractor that we use when generating documentation, it is a fork
+of the `@ts-docs/ts-extractor` NPM package that is used exclusively for fappen, but is kept in a separate repo
+to make it easier to track upstream changes.

docs/Guides/setup.md

@@ -0,0 +1,119 @@
+---
+name: Setup  
+order: 1
+---
+
+# Setup
+
+The project relies on several tools to build the application, most of which are managed through NPM
+there are however some tools that need extra attention to get setup. This document will cover how 
+to get the entire project setup and which parts are needed for each application component.
+
+|>[note] Directory paths mentioned in this document are given relative to the project root. Meaning `/scripts` refers to scripts folder at the root of the repository, not one at the root of your file-system.
+
+|> Due to a conflict in typescript version between the application and one of its dependencies, the `--force` option must always be included when running `npm install` or `npm i`.
+
+## Base application
+
+The base application refers to all the core components that don't rely on external services.
+This basically just excludes the stregsystem module. While we consider the songbook part of the
+base application, the build instructions are separated since it is in most cases preferred to
+use the prebuilt files.
+
+### Requirements
+
+ - A Node.js / NPM installation. Any recent version should work. It is known to work with v17.
+ - Prebuilt songbook files. (These will be available with each application release on GitHub).
+ - A local copy of the project (Use `git clone` to get one if you haven't already).
+
+### Setup procedure
+
+First you will want to extract the prebuilt songbook files into the `/pages/songbook` directory.
+Once this has been done you can run the following from the root folder of the project:
+
+```bash
+npm i --force
+npm start     # Start a development server
+```
+
+## Stregsystem
+
+The stregystem module is built upon the stregsystem API. For this reason you will want a
+local stregsystem instance running if you intend to do development on this module.
+
+### Requirements
+
+|>[note] Listed requirements are in addition to those of the base application.
+
+- A stregsystem instance with the stregsystem API available.
+  You will want to have persistent test-data enabled for optimal performance. 
+  - Refer to [stregsystemet/#320](https://github.com/f-klubben/stregsystemet/pull/320)
+    for more info in regard to availability of the API.
+  - Refer to [stregsystemet](https://github.com/f-klubben/stregsystemet) for more info
+    on setting up a local instance.
+
+### Setup procedure
+
+As current stregsystem versions do not allow CORS requests you will want to run a proxy
+that enables this. The easiest way to do this is by running `npm run cors-proxy`.
+
+Additionally, you will want to make sure that you have the `FA_DEV_API_URL` environment variable
+set correctly. It should be pointing to the `http://stregsystems-host/api` endpoint which, if using
+the default cors-proxy and stregsystem settings will be `http://localhost:8080/http://localhost:8000/api`.
+(Note that while it is used as an example, if you are using the default configuration you do not need to set anything).
+
+## Songbook
+
+The songbook is built from the [f-klubben/sangbog](https://github.com/f-klubben/sangbog) repository written
+in LaTeX, for this reason it needs to modified quite a bit before it is ready for use in the app.
+
+### Requirements
+
+- Python3.x
+- Pandoc - it has to be a fairly recent version. > 2.19 is known to work. 2.5 does not work.
+
+### Setup procedure
+
+From the project root, run the following:
+
+```bash
+git clone [email protected]:f-klubben/sangbog.git
+python util/build_songs.py
+```
+
+
+## Documentation
+
+The documentation is built using [ts-docs](https://github.com/ts-docs/ts-docs) with a custom extractor.
+The custom extractor is kept as a dependency in `/extern/ts-extractor-singlefile-modules`.
+
+### Setup procedure
+
+Before you can build the documentation you need to make sure that you have initiated and updated the git submodules.
+This is done as follows:
+```bash
+git submodules init
+git submodules update
+```
+
+Once the submodule has been initiated then run the `setup-doc-extractor` script from the project root. 
+
+```bash
+npm run setup-doc-extractor
+```
+
+If you have previously run `npm install` or `npm i` you will then have to run:
+
+```bash
+npm run reload-doc-extractor
+```
+
+If you are modifying the extractor this is also the command that you should run to update
+the installed version. If you have yet to run `npm install` do `npm i --force`.
+
+The documentation is built by running:
+
+```bash
+npm run build-docs
+```
+

docs/Guides/style_guide.md

@@ -0,0 +1,42 @@
+---
+name: Style Guide
+---
+
+# Style Guide
+
+This document outlines the guidelines for how to style your code,
+as well as how you should style visual elements in the application.
+
+## JavaScript/TypeScript
+
+For JS/TS code we have a strict guideline that is enforced by EsLint.
+As such, in this document, we will only outline things that are not
+covered by the linter configuration.
+
+The linter can be run by running `npx eslint <path/to/file1.ts> <path/to/file2.ts>`
+from the root folder of the project. Additionally, you may pass the `--fix` option
+to the command, which will make eslint fix many issues automatically.
+
+Additional guidelines:
+
+ - Generally it is preferred for variable and function names to specified
+   in `snake_case`.
+ - The names of types must always be written in `PascalCase`.
+ - When using `@ts-ignore` it is expected that you follow it up with the reason
+   for using ignoring. Example:
+   ```ts
+   // @ts-ignore - the analyzer does not know how to deal with `bundle-text` imports
+   import access_failure_msg from 'bundle-text:../components/stregsystem/access_failure.pug';
+   ```
+  - It is preferred to `export` at the declaration site of individual constructs rather
+    than export everything at the end of the file.
+
+## Visual components
+
+Generally we try to style components is such a way that they match the spirit
+of the original stregsystem, however due to the focus on the mobile platform 
+we do occasionally have to deviate from this.
+
+A useful rule of thumb:
+> Everything is styled like it's a table! Except tables!
+