New doc structure (#736)

Restructure Documentation to better represent user and developers needs.

10 files changed, 65 insertions, 39 deletions

diff --git a/docs/book.toml b/docs/book.toml
index d17a0f07..49be0156 100644
--- a/docs/book.toml
+++ b/docs/book.toml
@@ -5,9 +5,24 @@ language = "en"
 multilingual = false
 src = "src"
 
-# FIX: the link check prevents some pages to be generated
-#[output.linkcheck]
-#follow-web-links = false
-#traverse-parent-directories = false
-#warning-policy = "warn"
+[output.html.fold]
+    enable = true
+
+[output.linkcheck]
+# Should we check links on the internet? Enabling this option adds a
+# non-negligible performance impact
+#follow-web-links = true
+
+# Are we allowed to link to files outside of the book's root directory? This
+# may help prevent linking to sensitive files (e.g. "../../../../etc/shadow")
+traverse-parent-directories = true
+
+# How should warnings be treated?
+#
+# - "warn" will emit warning messages
+# - "error" treats all warnings as errors, failing the linkcheck
+# - "ignore" will ignore warnings, suppressing diagnostic messages and allowing
+#   the linkcheck to continuing
+warning-policy = "warn"
+
 #exclude = [ 'README.md' ]
diff --git a/BUILDING.md b/docs/src/BUILDING.md
index b0215d44..adc1d448 100644
--- a/BUILDING.md
+++ b/docs/src/BUILDING.md
@@ -16,7 +16,7 @@ Following packages are required:
 * curl
 * gcc
 
-A list of our test platforms can be found [here](docs/src/supported-platforms.md).
+A list of our test platforms can be found [here](./supported-platforms.md).
 
 ## Get the code
 
@@ -187,4 +187,4 @@ This will run all tests from the repository and sometime may take long time, `ca
 
 ```shell
 cargo test --bin tedge
-```
+```
\ No newline at end of file
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index ce72c859..361ba3fd 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -1,10 +1,11 @@
 # Summary
 
-## Introduction
-[Overview](001_overview.md)
+- [Summary](./SUMMARY.md)
 
-## Tutorials
-- [Tutorials](tutorials/README.md)
+- [Introduction](001_overview.md)
+
+- [User Documentation](user_doc.md)
+  - [Tutorials](tutorials/README.md)
     - [Connect my device to Cumulocity IoT](./tutorials/connect-c8y.md)
     - [Connect my device to Azure IoT](./tutorials/connect-azure.md)
     - [Send Thin Edge Json data](./tutorials/send-thin-edge-data.md)
@@ -13,8 +14,7 @@
     - [Write my software management plugin](./tutorials/write-my-software-management-plugin.md)
     - [Supported Operations Management for Cumulocity IoT](./tutorials/supported_operations.md)
 
-## How-to guides
-- [How-to Guides](howto-guides/README.md)
+  - [How-to Guides](howto-guides/README.md)
     - [Installation](howto-guides/002_installation.md)
     - [How to create a test certificate](./howto-guides/003_registration.md)
     - [How to connect a cloud end-point](./howto-guides/004_connect.md)
@@ -29,22 +29,28 @@
     - [How to access the logs on the device?](./howto-guides/014_thin_edge_logs.md)
     - [How to install thin-edge.io on any Linux OS (no deb support)?](./howto-guides/015_installation_without_deb_support.md)
     - [How to restart your thin-edge.io device](./howto-guides/016_restart_device_operation.md)
+    - [How to use apama software management plugin](./howto-guides/017_apama_software_management_plugin.md)
 
-## Reference guides
-- [Reference Guides](references/README.md)
-    - [The `tedge` command](./references/tedge.md)
-    - [The `tedge config` command](./references/tedge-config.md)
-    - [The `tedge cert` command](./references/tedge-cert.md)
-    - [The `tedge connect` command](./references/tedge-connect.md)
-    - [The `tedge disconnect` command](./references/tedge-disconnect.md)
-    - [The `tedge mqtt` command](./references/tedge-mqtt.md)
-    - [The Bridged Topics](./references/bridged-topics.md)
-    - [The Software Management Plugin API](./references/plugin-api.md)
-
-## Architecture
-- [Architecture](architecture/README.md)
+- [Developer Documentation](dev_doc.md)
+  - [Architecture](architecture/README.md)
     - [Thin Edge Json](architecture/thin-edge-json.md)
     - [The Mapper](architecture/mapper.md)
     - [Software Management](./architecture/software-management.md)
     - [Architecture FAQ](architecture/faq.md)
     - [Platform support](supported-platforms.md)
+
+  - [Write my own software management plugin](./tutorials/write-my-software-management-plugin.md)
+
+  - [APIs](api.md)
+    - [The Bridged Topics](./references/bridged-topics.md)
+    - [The Software Management Plugin API](./references/plugin-api.md)
+
+  - [Building](./BUILDING.md)
+
+- [Command Line Reference](references/README.md)
+  - [The `tedge` command](./references/tedge.md)
+  - [The `tedge config` command](./references/tedge-config.md)
+  - [The `tedge cert` command](./references/tedge-cert.md)
+  - [The `tedge connect` command](./references/tedge-connect.md)
+  - [The `tedge disconnect` command](./references/tedge-disconnect.md)
+  - [The `tedge mqtt` command](./references/tedge-mqtt.md)
\ No newline at end of file
diff --git a/docs/src/api.md b/docs/src/api.md
new file mode 100644
index 00000000..59b8f895
--- /dev/null
+++ b/docs/src/api.md
@@ -0,0 +1 @@
+# APIs
diff --git a/docs/src/dev_doc.md b/docs/src/dev_doc.md
new file mode 100644
index 00000000..8fe3c1db
--- /dev/null
+++ b/docs/src/dev_doc.md
@@ -0,0 +1,2 @@
+# Developer Documentation
+The Developer Documentation for everybody who is interested in extending thin-edge.io. For more deeper interested users this also might be interesting, even if not required to operate thin-edge.io.
diff --git a/docs/src/howto-guides/015_installation_without_deb_support.md b/docs/src/howto-guides/015_installation_without_deb_support.md
index 65e2d023..6615c23a 100644
--- a/docs/src/howto-guides/015_installation_without_deb_support.md
+++ b/docs/src/howto-guides/015_installation_without_deb_support.md
@@ -12,7 +12,7 @@ Out of the box `thin-edge.io` uses deb packages for an automated installation ([
 
 The prebuilt binaries can be obtained from `thin-edge.io` [repository releases](https://github.com/thin-edge/thin-edge.io/releases).
 
-By default `thin-edge.io` is built with 3 architectures in mind: `amd64 (x86_64)`, `arm64 (aarch64)` and `armhf` with gnulibc bindings, so if you are looking to install `thin-edge.io` on a different platform you have to build your own binaries from source which you can do easily if you follow the [Building `thin-edge.io`](../../../BUILDING.md) guide.
+By default `thin-edge.io` is built with 3 architectures in mind: `amd64 (x86_64)`, `arm64 (aarch64)` and `armhf` with gnulibc bindings, so if you are looking to install `thin-edge.io` on a different platform you have to build your own binaries from source which you can do easily if you follow the [Building `thin-edge.io`](./../BUILDING.md) guide.
 
 > Note: By default `thin-edge.io` is built with `GNU libc`, but it is possible to use `musl` instead.
 
@@ -65,8 +65,8 @@ If you have built the binaries from source you should install them on the target
 
 On most Linux distribution it should suffice to execute them as `root` to do the setup, but in some cases (eg, your system uses `useradd` instead of `adduser` package) more detailed instructions are documented:
 
-* [tedge](../../../configuration/debian/tedge/postinst)
-* [tedge-agent](../../../configuration/debian/tedge_agent/postinst)
-* [tedge-mapper](../../../configuration/debian/tedge_mapper/postinst)
+* [tedge](https://github.com/thin-edge/thin-edge.io/blob/main/configuration/debian/tedge/postinst)
+* [tedge-agent](https://github.com/thin-edge/thin-edge.io/blob/main/configuration/debian/tedge_agent/postinst)
+* [tedge-mapper](https://github.com/thin-edge/thin-edge.io/blob/main/configuration/debian/tedge_mapper/postinst)
 
 After following steps for all the components installed `thin-edge.io` should be operational.
diff --git a/docs/src/howto-guides/017_apama_software_management_plugin.md b/docs/src/howto-guides/017_apama_software_management_plugin.md
index 1cc42e9e..62420a3e 100644
--- a/docs/src/howto-guides/017_apama_software_management_plugin.md
+++ b/docs/src/howto-guides/017_apama_software_management_plugin.md
@@ -53,8 +53,8 @@ Once the software modules are added in the software repository, these can be ins
 
 Here are some test apama artefacts that you can use to test this plugin:
 
-1. Demo apama [project zip](../../../tests/PySys/plugin_apama/Input/quickstart.zip)
-2. Demo apama [monitor file](../../../tests/PySys/plugin_apama/Input/TedgeTestMonitor.mon)
+1. Demo apama [project zip](https://github.com/thin-edge/thin-edge.io/raw/main/tests/PySys/plugin_apama/Input/quickstart.zip)
+2. Demo apama [monitor file](https://github.com/thin-edge/thin-edge.io/raw/main/tests/PySys/plugin_apama/Input/TedgeTestMonitor.mon)
 
 Add these binaries as software packages in Cumulocity software repository by following the instructions in the previous section.
 Once added, this apama project can be installed on any target device.
diff --git a/docs/src/tutorials/device-monitoring.md b/docs/src/tutorials/device-monitoring.md
index df71f702..753d84ec 100644
--- a/docs/src/tutorials/device-monitoring.md
+++ b/docs/src/tutorials/device-monitoring.md
@@ -168,4 +168,4 @@ If your device is not connected yet see:
 
 ## Trouble shooting
 
-See here for [how to trouble shoot device monitoring?](../howto-guides/009_touble_shooting_monitoring.md)
+See here for [how to trouble shoot device monitoring?](../howto-guides/009_trouble_shooting_monitoring.md)
diff --git a/docs/src/tutorials/write-my-software-management-plugin.md b/docs/src/tutorials/write-my-software-management-plugin.md
index 7a8dbad4..0e2a34b9 100644
--- a/docs/src/tutorials/write-my-software-management-plugin.md
+++ b/docs/src/tutorials/write-my-software-management-plugin.md
@@ -192,11 +192,11 @@ $ myplugin install NAME [--module-version VERSION] [--file FILE]
 ```
 
 This command takes 1 mandatory argument and has 2 optional flags.
-- **NAME**: the name of the software module to be installed, e.g. `mosquitto`. [Mandatory]
+- **NAME**: the name of the software module to be installed, e.g. `mosquitto`. (Mandatory)
 - **VERSION**: the version to be installed. e.g. `1.5.7-1+deb10u1`.
   The version can be blank, so it's recommended to define the behaviour if a version is not provided. 
-  For example, always installs the "latest" version if a version is not provided. [Optional]
-- **FILE**: the path to the software to be installed. [Optional]
+  For example, always installs the "latest" version if a version is not provided. (Optional)
+- **FILE**: the path to the software to be installed. (Optional)
 
 The installation phase may fail due to the following reasons.
 An error must be reported if:
@@ -289,10 +289,10 @@ $ myplugin remove NAME [--module-version VERSION]
 
 This command takes 1 mandatory argument and 1 optional argument with a flag.
 
-- **NAME**: the name of the software module to be removed, e.g. `mosquitto`. [Mandatory]
+- **NAME**: the name of the software module to be removed, e.g. `mosquitto`. (Mandatory)
 - **VERSION**: the version to be installed. e.g. `1.5.7-1+deb10u1`.
   The version can be blank, so it's recommended to define the behaviour if a version is not provided.
-  For example, uninstall a software module regardless of its version if a version is not provided. [Optional]
+  For example, uninstall a software module regardless of its version if a version is not provided. (Optional)
 
 The uninstallation phase can be failed due to several reasons. An error must be reported if:
 - The module name is unknown.
@@ -404,6 +404,6 @@ That example exists immediately if one of the commands fails.
 You can also refer to:
 
 - the specification of the [Package Manager Plugin API](https://github.com/thin-edge/thin-edge.io/blob/main/docs/src/references/plugin-api.md).
-- [the APT plugin](https://github.com/thin-edge/thin-edge.io/tree/main/sm/plugins/tedge_apt_plugin) written in Rust. 
+- [the APT plugin](https://github.com/thin-edge/thin-edge.io/tree/main/plugins/tedge_apt_plugin) written in Rust. 
 - [the example Docker plugin](https://github.com/thin-edge/thin-edge.io/blob/main/sm/plugins/tedge_docker_plugin/tedge_docker_plugin.sh) written in POSIX standard shell script.
   This plugin can install/remove docker containers using docker image tags. This plugin is **not** to be used in production without necessary enhancements. It is to be used only as a reference to write your own plugin.
diff --git a/docs/src/user_doc.md b/docs/src/user_doc.md
new file mode 100644
index 00000000..cd8a87ca
--- /dev/null
+++ b/docs/src/user_doc.md
@@ -0,0 +1,2 @@
+# User Documentation
+This part of the documentation is meant for users, that want to use thin-edge.io with the feature set that is provided. If you want to develop something on top of thin-edge.io, head over to the [Developer Documentation](dev_doc.md). Even if you do not yet plan to develop for thin-edge.io some of the contents there might be of interest to you to get a deeper technical understanding.
\ No newline at end of file