iox-eclipse-iceoryx#136 Minor fixes in documenation

Signed-off-by: Simon Hoinkis <[email protected]>
ApexAI · Dec 31, 2020 · eaf12a5 · eaf12a5
1 parent 31ab6fe
commit eaf12a5
Show file tree

Hide file tree

Showing 15 changed files with 40 additions and 31 deletions.
diff --git a/doc/website/FAQ.md b/doc/website/FAQ.md
@@ -1,7 +1,6 @@
 # FAQ
 
 In this document are tips and hints documented which can help for troubleshooting on RouDi.
-From time to time, we will extend it.
 
 ## Available memory is insufficient
 
@@ -10,9 +9,9 @@ To avoid that you need to check how much shared memory your system offers. For e
 
     df -H /dev/shm
 
-## Termination of RouDi and Processes
+## Termination of RouDi and processes
 
 To avoid undefined behavior of iceoryx posh it is recommended to terminate RouDi and the corresponding middleware
 processes with SIGINT or SIGTERM. In RouDi, we have integrated a sighandler that catches the signals and gives RouDi
 the chance to exit and clean-up everything. This also applies for processes. Therefore, we recommend adding a signalhandler
-to your process (see example: https://github.com/eclipse/iceoryx/blob/master/iceoryx_examples/icedelivery/iox_publisher_untyped.cpp)
+to your process (see [this example](https://github.com/eclipse/iceoryx/blob/master/iceoryx_examples/icedelivery/iox_publisher_untyped.cpp)).
diff --git a/doc/website/getting-started/advanced-examples.md b/doc/website/getting-started/advanced-examples.md
@@ -1,8 +1,4 @@
 # Advanced examples
 
-<!-- {! ./../iceoryx_examples/ice_multi_publisher/README.md !}  Rewrite this to use icedelivery -->
-{! ./../iceoryx_examples/waitset/README.md !}
-{! ./../iceoryx_examples/waitset_on_c/README.md !}
-{! ./../iceoryx_examples/singleprocess/README.md !}
-{! ./../iceoryx_examples/icecrystal/README.md !}
+{! ./../iceoryx_examples/icecrystal/Readme.md !}
 {! ./../iceoryx_examples/iceperf/README.md !}
diff --git a/doc/website/getting-started/basic-examples.md b/doc/website/getting-started/basic-examples.md
@@ -2,4 +2,3 @@
 
 {! ./../iceoryx_examples/icedelivery/README.md !}
 {! ./../iceoryx_examples/icedelivery_on_c/README.md !}
-<!-- {! ./../iceoryx_examples/README.md !} -->
diff --git a/doc/website/getting-started/installation.md b/doc/website/getting-started/installation.md
@@ -27,7 +27,7 @@ make install
 ```
 
 If you would like to use our Cyclone DDS Gateway you have to install Cyclone DDS first, see
-[https://github.com/eclipse-cyclonedds/cyclonedds](https://github.com/eclipse-cyclonedds/cyclonedds).
+[here](https://github.com/eclipse-cyclonedds/cyclonedds).
 
 ### Linux
 
@@ -163,7 +163,7 @@ If you want to execute only individual testcases then you can use these executab
 <!-- Move this to advanced-building.md -->
 
 Due to the fact that iceoryx works a lot with system memory it should be ensured that errors like memory leaks are not introduced.
-To prevent these, we use the clang toolchain which offers several tools for scanning the codebase. One of them is the Adress-Sanitizer which checks for example on dangling pointers: [https://clang.llvm.org/docs/AddressSanitizer.html](https://clang.llvm.org/docs/AddressSanitizer.html)
+To prevent these, we use the clang toolchain which offers several tools for scanning the codebase. One of them is the [Address-Sanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) which checks for example on dangling pointers.
 
 In iceoryx are scripts available to do the scan on your own. Additionally the Scans are running on the CI in every Pull-Request.
 As Requirement you should install the clang compiler:

diff --git a/doc/website/getting-started/intermediate-examples.md b/doc/website/getting-started/intermediate-examples.md
@@ -0,0 +1,5 @@
+# Intermediate examples
+
+{! ./../iceoryx_examples/waitset/README.md !}
+{! ./../iceoryx_examples/waitset_on_c/README.md !}
+{! ./../iceoryx_examples/singleprocess/README.md !}
diff --git a/doc/website/introduction.md → doc/website/index.md b/doc/website/introduction.md → doc/website/index.md
diff --git a/iceoryx_examples/README.md b/iceoryx_examples/README.md
@@ -20,13 +20,13 @@ cd someExample
 
 ## List of all examples
 
-| example                                                | description |
-|:-------------------------------------------------------|:------------|
-|[icecrystal](./icecrystal/)                             | Demonstrates the usage of the iceoryx introspection client. |
-|[icedelivery](./icedelivery/)                           | You are new to iceoryx then take a look at this example which demonstrates the basics of iceoryx by sending data from one process to another process. |
-|[icedelivery_on_c](./icedelivery_on_c/)                 | Shows the same use case as the ice delivery example but with the iceoryx C API  |
-|[iceperf](./iceperf/)                                   | A benchmark application which measures the latency of an IPC transmission between two applications. |
-|[singleprocess](./singleprocess/)                       | Iceoryx can also be used for inter thread communication when you would like to run everything in a single process. |
-|[ice_multi_publisher](./ice_multi_publisher/)           | Shows how multiple publishers can be used to publish on the same topic. |
-|[waitset](./waitset/)                       | Explaining the structure, usage and ideas behind the WaitSet. |
-|[waitset_on_c](./waitset_on_c/)                 | The C example of our WaitSet. |
+| Example                                                | Description |Level |
+|:-------------------------------------------------------|:------------|:----:|
+|[icedelivery](./icedelivery/)                           | You are new to iceoryx then take a look at this example which demonstrates the basics of iceoryx by sending data from one process to another process. | Beginner |
+|[icedelivery_on_c](./icedelivery_on_c/)                 | Shows the same use case as the ice delivery example but with the iceoryx C API  | Beginner |
+|[ice_multi_publisher](./ice_multi_publisher/)           | Shows how multiple publishers can be used to publish on the same topic. | Intermediate |
+|[waitset](./waitset/)                       | Explaining the structure, usage and ideas behind the WaitSet. | Intermediate |
+|[waitset_on_c](./waitset_on_c/)                 | The C example of our WaitSet. | Intermediate |
+|[singleprocess](./singleprocess/)                       | Iceoryx can also be used for inter thread communication when you would like to run everything in a single process. | Intermediate |
+|[iceperf](./iceperf/)                                   | A benchmark application which measures the latency of an IPC transmission between two applications. | Advanced |
+|[icecrystal](./icecrystal/)                             | Demonstrates the usage of the iceoryx introspection client. | Advanced |
diff --git a/iceoryx_examples/ice_multi_publisher/README.md b/iceoryx_examples/ice_multi_publisher/README.md
@@ -1,5 +1,7 @@
 # Multiple publishers for the same topic
 
+<!-- Rewrite this document to re-use icedelivery -->
+
 ## Introduction
 A common use case is that often we have multiple sensors sending data of the same type, e.g. LIDAR data, and a subscriber is interested in the data of all those sensors. 
 

diff --git a/iceoryx_examples/icecrystal/Readme.md b/iceoryx_examples/icecrystal/Readme.md
@@ -25,11 +25,9 @@ build/iceoryx_examples/icedelivery/iox-ex-subscriber-untyped
 build/iox-introspection-client --all
 ```
 
-<!-- ## Expected output -->
-
 <!-- @todo Add expected output of RouDi, publisher, subscriber and introspection with asciinema recording before v1.0-->
 
-### Iceoryx introspection application
+## Expected output
 
 ![introspection_screenshot](https://user-images.githubusercontent.com/22388003/75041206-672feb80-54bc-11ea-8621-2acf95bf376e.png)
 

diff --git a/iceoryx_examples/icedelivery_on_c/README.md b/iceoryx_examples/icedelivery_on_c/README.md
@@ -2,14 +2,18 @@
 
 You can find a more detailled description of the C API in the [iceoryx_binding_c README.md](../../iceoryx_binding_c)
 
-## The icedelivery example
+## Introduction
 
 The behavior and structure is identical to the [icedelivery C++ example](../icedelivery/)
 so that we explain here only the C API differences and not the
 underlying mechanisms.
 
+## Expected output
+
 <!-- @todo Add expected output with asciinema recording before v1.0-->
 
+## Code walthrough
+
 ### Subscriber
 
 Like in the

diff --git a/iceoryx_examples/iceperf/README.md b/iceoryx_examples/iceperf/README.md
@@ -37,14 +37,15 @@ iceperf-hardy with the parameter `cpp-api` or `c-api`.
     build/iceoryx_examples/iceperf/iceperf-laurel 100000 cpp-api
 
     build/iceoryx_examples/iceperf/iceperf-hardy cpp-api
+```
 
 ## Expected output
 
 The numbers will differ depending on parameters and the performance of the hardware.
 Which technologies are measured depends on the operating system (e.g. no message queue on MacOS).
 Here an example output with Ubuntu 18.04 on Intel(R) Xeon(R) CPU E3-1505M v5 @ 2.80GHz.
 
-<!-- @todo Replace this with asciinema recording before v1.0-->
+<!-- @todo Replace this with asciinema recording before v1.0 -->
 
 ### iceperf-laurel application
 

diff --git a/iceoryx_examples/singleprocess/README.md b/iceoryx_examples/singleprocess/README.md
@@ -1,4 +1,4 @@
-# singleprocess
+# Single process
 
 ## Introduction
 

diff --git a/iceoryx_examples/waitset/README.md b/iceoryx_examples/waitset/README.md
@@ -13,7 +13,7 @@ attaches one shot events. These are events which will trigger the WaitSet only o
 
 ## Threadsafety
 The WaitSet is **not** threadsafe!
-- It is **not** allowed to attach or detach _Triggerable
+- It is **not** allowed to attach or detach _Triggerable_
    classes with `attachEvent` or `detachEvent` when another thread is currently
    waiting for events with `wait`.
 

diff --git a/iceoryx_examples/waitset_on_c/README.md b/iceoryx_examples/waitset_on_c/README.md
@@ -1,4 +1,4 @@
-# WaitSet C binding
+# WaitSet in C
 
 ## Introduction
 
@@ -8,8 +8,12 @@ not the WaitSet in general. For that we will take a look at the same use case
 as the [waitset C++ example](../waitset). The examples are also structured 
 in the same way as the C++ ones.
 
+## Expected output
+
 <!-- @todo Add expected output with asciinema recording before v1.0-->
 
+## Code walthrough
+
 To run an example you need a running `iox-roudi` and the waitset publisher
 `iox-ex-c-waitset-publisher`. They are identical to the ones introduced
 in the [icedelivery C example](../icedelivery_on_c).

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -3,18 +3,19 @@ site_url: https://iceoryx.io
 repo_url: https://github.com/eclipse/iceoryx
 docs_dir: doc/website/
 nav:
-  - introduction.md
+  - index.md
   - Getting started:
     - getting-started/overview.md
     - getting-started/installation.md
     - Examples:
       - getting-started/basic-examples.md
+      - getting-started/intermediate-examples.md
       - getting-started/advanced-examples.md
   - API-References.md
   - API-Cheatsheet.md
   - FAQ.md
   - Advanced:
-    - for-developers/iceoryx_utils.md
+    - Standard library: for-developers/iceoryx_utils.md
     - for-developers/usage-guide.md
 markdown_extensions:
   - markdown_include.include:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,3 @@

		{! ./../iceoryx_examples/icedelivery/README.md !}
		{! ./../iceoryx_examples/icedelivery_on_c/README.md !}
		<!-- {! ./../iceoryx_examples/README.md !} -->