docs: restructure docs

README.md

@@ -4,13 +4,15 @@ IRNAS template for a GitHub repository. It comes with a
 [Zephyr group](https://github.com/IRNAS/irnas-workflows-software/tree/main/workflow-templates/zephyr)
 of CI workflows for release automation.
 
+The project's documentation can be found in the [doc/](./doc/README.md) folder.
+
 ## Checklist
 
 ### General GitHub setup
 
 - [ ] Provide a concise and accurate description of your project in the GitHub "description" field.
 - [ ] Provide a concise and accurate description of your project in this `README.md` file, replace
-      the title.
+      the title. Make sure that you leave the link to the documentation there.
 - [ ] Ensure that your project follows [repository naming scheme].
 
 ### Tooling
@@ -21,9 +23,11 @@ of CI workflows for release automation.
 
 ### Zephyr specifics
 
-- [ ] Select the version of NCS in the `west.yaml` file, check the below section for specifics.
-- [ ] Provide repository setup instructions, use template in _Setup_ section below. Replace
-      `<repo-name>`, `<board_name>`, and `<build_type>` as appropriate for your project.
+- [ ] Select the version of NCS in the `west.yaml` file, check the
+      [west.yml_usage document](./docs/development/west_yml_usage.md) for more information.
+- [ ] Provide repository setup instructions, use the template in the
+      [Setup document](./docs/development/setup.md). Replace `<repo-name>` and `<board_name>` as
+      appropriate for your project.
 
 ### GitHub Actions
 
@@ -59,99 +63,16 @@ of CI workflows for release automation.
 [CodeChecker server]:
   https://github.com/IRNAS/irnas-codechecker-software?tab=readme-ov-file#creating-new-products---codechecker-integration-in-east
 
-## Setup
-
-If you do not already have them you will need to:
-
-- [install west](https://docs.zephyrproject.org/3.6.0/develop/west/install.html)
-- [install east](https://github.com/IRNAS/irnas-east-software)
-
-Then follow these steps:
-
-```shell
-east init -m https://github.com/IRNAS/<repo-name> <repo-name>
-cd <repo-name>/project
-
-# Set up east globally (this only needs to be done once on each machine)
-east install nrfutil-toolchain-manager
-# Install toolchain for the version of NCS used in this project
-east install toolchain
-
-# Run `west update` via east to set up west modules in the repository
-east update
-
-# Create default VERSION files
-make gen-version
-```
-
-### Setup `pre-commit`
-
-Turn on `pre-commit` tool by running `pre-commit install`. If you do not have it yet, follow
-instructions [here](https://github.com/IRNAS/irnas-guidelines-docs/tree/main/tools/pre-commit).
-
-## Building and flashing
-
-To build the application firmware:
-
-```bash
-cd app
-east build -b <board_name> -u <build_type>
-```
-
-To flash the firmware:
-
-```bash
-east flash
-```
-
-To view RTT logs:
-
-```bash
-# Run in first terminal window
-east util connect
-
-# Run in second, new terminal window
-east util rtt
-```
-
-## west.yaml and name-allowlist
-
-The manifest file (`west.yaml`) that comes with this template by default only allows certain modules
-from Nordic's `sdk-nrf` and `sdk-zephyr` repositories, while ignoring/blocking others.
-
-This means that a setup on the new machine and in CI is faster as the `east update` command does not
-clone all modules from the mentioned repositories but only the ones that are needed.
-
-Manifest file only allows modules that are commonly used by IRNAS, however this can be easily
-changed by uncommenting the required modules and running `east update`.
-
-**IMPORTANT:** Such improvements do not come with some tradeoffs, there are now two things that a
-developer must take note of.
-
-### Compile time errors cause of blocked/missing headers
-
-If the application source code includes some headers from blocked/missing modules or if included
-headers use blocked/missing modules you will get an error that will complain about missing header
-files. In that case, you have to go to manifest file, find commented module, run `east update`,
-return to the app folder, delete build folder and build again.
-
-### Updating `sdk-nrf` version
-
-Whenever you want to update the version of `sdk-nrf` (also know simply as `NCS`) you need to keep
-one general thing in mind: you need to manually keep revisions of `sdk-nrf` and `sdk-zephyr`
-projects, as well as their imports in sync.
-
-1. Open `west.yml` file in `sdk-nrf` repository ([link](https://github.com/nrfconnect/sdk-nrf)).
-   Make sure that you select correct tag from selection from top-left dropdown menu.
-2. Check what repos are under `sdk-zepyhr` project's `name-allowlist`, those should match the repos
-   in `west.yaml` of your project (and this template), under `sdk-zepyhr` project's
-   `name-allowlist`. Most of the time they should be commented out, but depends.
-3. Check what other repositories appear under `sdk-zepyhr` project as standalone projects, they
-   start appearing around line 100, after `NCS repositories` comment. This projects should match the
-   repos in `west.yaml` of your project (and this template), under `sdk-nrf` project's
-   `name-allowlist`. Most of the time they should be commented out, but again, this depends.
-
-When a new `sdk-nrf` version is released, some new repos as `NCS repositories` might appear or be
-moved into `sdk-zephyr`.
-
-After any change to the `west.yaml` do not forget to run `east update`.
+## Repository folder structure
+
+- `app` - The main application code, intended to be used in the production.
+- `boards` - Board definitions files for custom boards.
+- `doc` - Project and development documentation.
+- `drivers` - Low-level drivers for peripherals.
+- `dts` - Device tree bindings file.
+- `samples` - Sample/example code, used either to demonstrate the use or functionality of smaller
+  parts of the main application code or used for some testing purposes.
+- `scripts` - Various scripts used for development, testing, or automation.
+- `subsys` - Subsystem and libraries used by the application and samples.
+- `tests` - Firmware used exclusively for unit testing testing or integration testing purposes.
+- `.github` - GitHub Actions workflows and other GitHub related files.

doc/README.md

@@ -0,0 +1,7 @@
+# Documentation
+
+This folder contains several different kinds of documentation:
+
+- [Development documents](./development/README.md) - Instructions on how to setup the development
+  environment, how to write unit tests, use test runner and generate release artifacts can be found
+  in the `development` folder.

doc/development/README.md

@@ -0,0 +1,7 @@
+# Development documents
+
+- [Setup](./setup.md) - How to clone this repository to local machine and set up the development
+  environment.
+- [West.yml usage](./west_yml_usage.md) - How to use `west.yml` file to manage dependencies.
+- [Writing Unit tests](./unit_tests.md) - How to write unit tests for the firmware.
+- [Using Twister](./twister.md) - How to use the Twister test runner.

doc/development/setup.md

@@ -0,0 +1,30 @@
+# Development Setup
+
+If you do not already have them you will need to:
+
+- [install west](https://docs.zephyrproject.org/latest/develop/west/install.html)
+- [install east](https://github.com/IRNAS/irnas-east-software)
+
+Then follow these steps:
+
+```shell
+east init -m https://github.com/IRNAS/<repo-name> <repo-name>
+cd <repo-name>/project
+
+# Set up east globally (this only needs to be done once on each machine)
+east install nrfutil-toolchain-manager
+# Install toolchain for the version of NCS used in this project
+east install toolchain
+
+# Run `west update` via east to set up west modules in the repository
+east update
+
+# Create default VERSION files
+make gen-version
+```
+
+## Setup `pre-commit`
+
+Turn on `pre-commit` tool by running `pre-commit install`. If you do not have it yet **or the
+command did not succeed** follow instructions
+[here](https://github.com/IRNAS/irnas-guidelines-docs/tree/main/tools/pre-commit).

doc/development/twister.md

@@ -0,0 +1,93 @@
+# Twister
+
+Twister is a script that scans for the set of unit test applications in the git repository and
+attempts to execute them. For listed boards, it can build the applications, run them, check if they
+every successful and generate a report.
+
+Due to the number of features that it has it can take some time to figure out how to do something
+that you want, see `east twister --extra-help` for the supported options.
+
+Also, see [Zephyr's documentation](https://docs.zephyrproject.org/latest/develop/test/twister.html)
+for more info.
+
+## Simple example
+
+From the project's root directory run:
+
+```shell
+east twister -p native_sim -T tests
+```
+
+Twister will detect all projects with `testcase.yaml` in their project root under `tests` directory
+and execute them.
+
+To run the same thing on the target you need to provide more info to the Twister:
+
+```shell
+east twister -T tests -p nrf52dk_nrf52832 --device-testing --device-serial /dev/ttyACM0
+```
+
+Check the output for the results.
+
+## `twister-out` folder
+
+With every invocation of the `east twister` a `twister-out` folder is created. It contains all build
+folders of the created projects, as well as the report files.
+
+Keep in mind, if you keep running `east twister` command and not deleting the `twister-out` folder,
+then the command will rename it to `twister-out.X` (Where `X` is a unique ascending number, starting
+with 1) before running the full build.
+
+## `testcase.yaml` file
+
+`testcase.yaml` file marks that a Twister should pick up the test folder and build it. Its content
+defines for which platforms it should be built and tested.
+
+See [Test Cases] section for more info.
+
+[test cases]: https://docs.zephyrproject.org/latest/develop/test/twister.html#test-cases
+
+## Coverage report
+
+Twister supports creating coverage reports from test runs with `gcovr` tool. Adding extra flags to
+the command invocation creates an html file (among others) which shows code coverage for each file.
+
+```shell
+east twister -T tests -p native_sim --coverage  --coverage-tool gcovr
+```
+
+Note that you might need to change `--coverage-basedir` or add new ones for your project.
+
+To open the coverage report in the browser:
+
+```shell
+firefox twister-out/coverage/index.html
+```
+
+## Make commands
+
+`makefile` in the root of the project contains useful targets for running tests.
+
+To setup host machine for running tests (needed to be run only once):
+
+```shell
+make install-dep
+```
+
+To run all tests with Twister:
+
+```shell
+make test
+```
+
+To see unit test results:
+
+```shell
+make test-report
+```
+
+To see code coverage report:
+
+```shell
+make coverage-report
+```