Improve service documentation

.devcontainer/Dockerfile

@@ -28,14 +28,14 @@ RUN apt-get update && apt-get install -y ca-certificates openssl git curl golang
     latest) \
     export VERSION=$(curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest | grep "tag_name" | awk '{print substr($2, 3, length($2)-4)}') ;;\
     esac && \
-    echo ${VERSION} && \
+    echo Wanted Hugo version is ${VERSION} && \
     case $(uname -m) in \
     aarch64) \
     export ARCH=ARM64 ;; \
     *) \
     export ARCH=64bit ;; \
     esac && \
-    echo ${ARCH} && \
+    echo Wanted Architecture is ${ARCH} && \
     wget -O ${VERSION}.tar.gz https://github.com/gohugoio/hugo/releases/download/v${VERSION}/${VARIANT}_${VERSION}_Linux-${ARCH}.tar.gz && \
     tar xf ${VERSION}.tar.gz && \
     mv hugo /usr/bin/hugo

.devcontainer/scripts/postCreateCommand.sh

@@ -20,9 +20,11 @@ export NODE_PATH=$NODE_PATH:`npm root -g`
 npm install -g npm
 npm install -g postcss postcss-cli autoprefixer
 npm install
-hugo mod get -u github.com/google/docsy@v0.6.0
+hugo mod get -u github.com/google/docsy@v0.11.0
 
 # install pre-commit
+sudo apt update
+sudo apt install -y python3-pip
 pip install pre-commit==3.6.0 --break-system-packages
 
 # add repo to git safe.directory & fix hugo issue with server start

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,6 +4,4 @@
 
 ## Checklist before requesting a review
 - [ ] I have performed a self-review of my code
-- [ ] If it is a core feature, I have added thorough tests.
-- [ ] Do we need to implement analytics?
 - [ ] Will this be part of a product update? If yes, please write one phrase about this update.

.github/workflows/ci.yml

@@ -17,8 +17,7 @@ name: CI workflow
 on:
   workflow_dispatch:
   push:
-    branches:
-      - "main"
+  pull_request:
 
 jobs:
   Build-documentation:
@@ -34,6 +33,11 @@ jobs:
           hugo-version: "0.123.3"
           extended: true
 
+      - name: Verify that devcontainer works
+        run: |
+          cd .devcontainer
+          docker buildx build -f Dockerfile -t test:latest .
+
       - name: Build
         run: |
           export NODE_PATH=$NODE_PATH:`npm root -g`
@@ -56,6 +60,8 @@ jobs:
         # Note that gh_pages isnt published to https://eclipse-velocitas.github.io/velocitas-docs/
         # or the alias https://eclipse.dev/velocitas/
         # So this basically just check if there are errors :-)
+        # Only publish to gh_pages if this was a push to master
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
         uses: peaceiris/[email protected]
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -1,8 +1,51 @@
-# Velocitas
+# Velocitas-Docs
 
 [![License: Apache](https://img.shields.io/badge/License-Apache-yellow.svg)](http://www.apache.org/licenses/LICENSE-2.0)
 
-:notebook: **Please visit our documentation to learn more about it:** <https://eclipse.dev/velocitas/>
+This repository contains the source code for the Velocitas Documentation.
+
+:notebook: **Please visit the generated documentation to learn more about Velocitas!** <https://eclipse.dev/velocitas/>
+
+## Directory structure
+
+* Markdown files used for the generated documentation exists in the `content` folder.
+* Examples shown in the documentation may exist as source code in the `examples`folder.
+
+## Building documentation locally
+
+### Using Devcontainer
+
+Velocitas-docs provides a  [Devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) that can be used to build and run the documentation server locally.
+As the last step when starting the devcontainer the webserver is started, and it is reachable outside Devcontainer.
+If you update source pages the local server will be automatically updated.
+
+`Web Server is available at http://localhost:1313/velocitas/ (bind address 127.0.0.1)`
+
+### Using Native Envioronment
+
+It is also possible to build and run the documentation outside the Devcontainer. If using Debian you could install Hugo like this:
+
+`sudo apt install hugo`
+
+For other environments please visit [Hugo documentation](https://gohugo.io/installation/).
+
+Then you can build and start a local hugo server and access documentation at `http://localhost:1313`.
+
+`/usr/bin/hugo server -D -s .`
+
+If you update source pages the local server will be automatically updated.
+
+## Deploying official documentation
+
+The Velocitas Documentation Site is not automatically updated when something is merged to main.
+Instead a Velocitas committer needs to manually run the `Publish Documentation` workflow.
+That results in that the `docs` branch is updated and triggers the `pages-build-deployment` workflow that publishes the new version to the Velocitas Documentation Site.
+
+## Theme Upgrade
+
+Velocitas-docs use the [Docsy Theme](https://github.com/google/docsy).
+To upgrade change version in [postCreateCommand.sh](.devcontainer/scripts/postCreateCommand.sh). Then rebuild the devcontainer.
+This will result in that `go.mod`and `go.sum` gets updated.
 
 ## Community
 

content/en/docs/tutorials/grpc_service_generation/_index.md

@@ -6,12 +6,54 @@ description: >
   Learn how to generate and fill your own gRPC services.
 ---
 
-This tutorial shows how to generate a basic gRPC service like a seat service. For this example the proto file under <https://raw.githubusercontent.com/eclipse-kuksa/kuksa-incubation/0.4.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto> is taken.
+This tutorial shows how to generate a basic gRPC service like a seat service. For this example the proto file at <https://raw.githubusercontent.com/eclipse-kuksa/kuksa-incubation/0.4.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto> is used.
 
 All files included from `services/seats` are auto-generated and added to the app project as Conan dependency.
 For writing a complete gRPC service you need two velocitas apps/projects.
 One is implementing a client and the other one is for providing the server.
-To complete the server implementation you have to fill the generated `*ServiceImpl.cpp`.
-Have a look at the linked content beneath for a tutorial how it would be done for a SeatService leveraging <https://raw.githubusercontent.com/eclipse-kuksa/kuksa-incubation/0.4.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto>.
 
-To run the example you need to start the velocitas app for the server first and then the second velocitas app for the client.
+## Networking
+
+The examples shown in this tutorial are based on three components running:
+
+* A client using the API defined in the proto file
+* A server providing the API and communicating with Databroker to read or modify datapoints
+* A [Kuksa Databroker](https://github.com/eclipse-kuksa/kuksa-databroker).
+
+As a Velocitas developer you may use the [Velocitas devenv-runtimes](https://github.com/eclipse-velocitas/devenv-runtimes) to deploy and run the Databroker instance, but it is also possible to connect to a Databroker running on localhost.
+The setup used for the examples have been as followed:
+
+* One Velocitas Devcontainer running the Client, based on the [Vehicle App C++ Template](https://github.com/eclipse-velocitas/vehicle-app-cpp-template).
+* One Velocitas Devcontainer running the Server, based on the [Vehicle App C++ Template](https://github.com/eclipse-velocitas/vehicle-app-cpp-template).
+* Databroker running on localhost.
+
+For this to work the `.devcontainer/devcontainer.json` was changed.
+In the setup `--network=host` was added to allow the containers to use the host network, 
+and for the server `forwardPorts": [ 5555 ]` was used to forward port 5555.
+
+```
+    "forwardPorts": [ 5555 ],
+	"runArgs": [
+		"--init",
+		"--privileged",
+		"--cap-add=SYS_PTRACE",
+		"--network=host",
+		"--security-opt",
+		"seccomp=unconfined"
+	],
+```
+
+Note that changes to `.devcontainer/devcontainer.json` may be overwritten when `velocitas sync`is performed.
+
+## Running the examples
+
+To run the examples the following actions needs to be performed in the following order:
+
+* Databroker needs to be started. 
+  If using a Databroker on host make sure that it is compatible with the Velocitas version you are using
+  The catalog used must also be compatible with the signals used in the example
+* Set the current value of `Vehicle.Cabin.Seat.Row1.DriverSide.Position` to a valid value, for example 12, using a Databroker Client ([Kuksa Python Client](https://pypi.org/project/kuksa-client/) or [Databroker CLI](https://github.com/eclipse-kuksa/kuksa-databroker))
+* Start the server
+* Start the client
+* Verify that no (unexpected) errors are reported
+* Use the Databroker Client to verify that the target value of `Vehicle.Cabin.Seat.Row1.DriverSide.Position` has been set to 75

content/en/docs/tutorials/grpc_service_generation/create_client.md

@@ -6,48 +6,64 @@ description: >
   Learn how to create a client for a service definition.
 ---
 
+# Introduction
 
-## App configuration
+This example assumes that you have used the [Velocitas App C++ Template](https://github.com/eclipse-velocitas/vehicle-app-cpp-template) to create a new repository and now want to modify it to be a grpc service client.
+The example files can also be found in the [Github repository](https://github.com/eclipse-velocitas/velocitas-docs/examples/grpc_client).
+
+# Velocitas components
+
+Dependning on how you intend to deploy the Application and Databroker the number of Velocitas components required varies.
+Below is the minimum set needed in `.velocitas.json` if deploying Databroker on localhost.
 
 ```json
-{
-  "type": "grpc-interface",
-  "config": {
-      "src": "https://raw.githubusercontent.com/eclipse-kuksa/kuksa-incubation/0.4.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto",
-      // "required" indicates you are trying to write a client for the service
-      "required": {
-        "methods": [
-          "Move", "CurrentPosition"
-        ]
-      },
-  }
-}
+    "components": [
+        "devcontainer-setup",
+        "grpc-interface-support",
+        "sdk-installer",
+        "build-system"
+    ],
 ```
 
-## Project configuration
+## App configuration
+
+In the `AppManifest.json` file you need to specify which interfaces your App wants to use or provide.
+In this case it declares that it wants to use `Move` and `CurrentPosition` from the Seats service defined in `seats.proto`.
 
-You need to specify `devenv-devcontainer-setup` >= `v2.4.2` in your project configuration. Therefore your `.veloitas.json` should look similair to this example:
 
 ```json
 {
-  "packages": {
-    "devenv-devcontainer-setup": "v2.4.2"
-  },
-  "components": [
-    {
-      "id": "grpc-interface-support", 
-    }
-  ],
+    "manifestVersion": "v3",
+    "name": "SampleApp",
+    "interfaces": [
+        {
+            "type": "grpc-interface",
+            "config": {
+                "src": "https://raw.githubusercontent.com/eclipse-kuksa/kuksa-incubation/0.4.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto",
+                "required": {
+                    "methods": [
+                        "Move", "CurrentPosition"
+                    ]
+                }
+            }
+        }
+    ]
 }
 ```
 
-To do that you can run `velocitas component add grpc-interface-support` when your package is above or equal to v2.4.2
+## File Generation
+
+When rebuilding the devcontainer with the configuration no new files will appear in your repository,
+but the SDK has been updated in the background so you can use it in the file containing `main()`.
+You can also regenerate the SDK with the `(Re-)generate gRPC SDKs` task.
 
-## Example code
+## Launcher.cpp
 
-To create a client we use the generated `SeatsServiceClientFactory.h` and `seats.grpc.pb.h`. These define request and response types and the operations that are available. An example implementation for the SeatService follows:
+You need to have a file that implements the client behavior,
+in this example we modify the file `Launcher.cpp` that already exist in the [template](https://github.com/eclipse-velocitas/vehicle-app-cpp-template).
 
-### main.cpp
+The logic of the example client is simple. It tries to set the target position for the seat and if it
+succeeds it tries to read current position.
 
 ``` cpp
 #include <sdk/middleware/Middleware.h>
@@ -59,6 +75,13 @@ To create a client we use the generated `SeatsServiceClientFactory.h` and `seats
 using namespace velocitas;
 
 int main(int argc, char** argv) {
+    // The default Velocitas Middleware class performs service discovery by
+    // environment variables.
+    // For this client it expects SDV_SEATS_ADDRESS to be defined
+    // for example:
+    // export SDV_SEATS_ADDRESS=grpc://127.0.0.1:5556
+
+    std::cout << "Starting " << std::endl;
     auto serviceClient = SeatsServiceClientFactory::create(Middleware::getInstance());
 
     ::grpc::ClientContext                        context;
@@ -72,9 +95,8 @@ int main(int argc, char** argv) {
     seat_location.set_index(1);
 
     ::sdv::edge::comfort::seats::v1::Position seat_position;
-    // we only set base here to keep the example simple
-    // extend here if yu want to set lumbar etc.
-    seat_position.set_base(1000);
+
+    seat_position.set_base(75.0);
 
     seat.set_allocated_location(&seat_location);
     seat.set_allocated_position(&seat_position);
@@ -86,7 +108,8 @@ int main(int argc, char** argv) {
     std::cout << "gRPC Server returned code: " << status.error_code() << std::endl;
     std::cout << "gRPC error message: " << status.error_message().c_str() << std::endl;
 
-    if (status.error_code() == ::grpc::StatusCode::UNIMPLEMENTED) {
+    if (status.error_code() != ::grpc::StatusCode::OK) {
+        // Some error
         return 1;
     } else {
         ::grpc::ClientContext                                   context;
@@ -96,11 +119,34 @@ int main(int argc, char** argv) {
         request.set_row(1);
         request.set_index(1);
 
-        auto status_curr_pos = seatService->CurrentPosition(&context, request, &response);
-        std::cout << "current Position:" << response.seat().position().base() << std::endl;
+        auto status_curr_pos = serviceClient->CurrentPosition(&context, request, &response);
         std::cout << "gRPC Server returned code: " << status_curr_pos.error_code() << std::endl;
         std::cout << "gRPC error message: " << status_curr_pos.error_message().c_str() << std::endl;
+        if (status_curr_pos.ok())
+            std::cout << "current Position:" << response.seat().position().base() << std::endl;
         return 0;
     }
 }
 ```
+
+## Building and Running
+
+To (re-)build the App after changing the code you can use the [build script](https://github.com/eclipse-velocitas/vehicle-app-cpp-template/blob/main/build.sh).
+As preparation for running you must also set an environment variables to define the address/port of the server.
+
+```bash
+./build.sh
+export SDV_SEATS_ADDRESS=grpc://127.0.0.1:5555
+```
+
+If Databroker and the Server is running and has a current value for the wanted signal, then everthing shall work when the client is started.
+Output similar to below is expected.
+
+```bash
+vscode ➜ /workspaces/erik_vapp_241018 (main) $ build/bin/app
+Starting 
+gRPC Server returned code: 0
+gRPC error message: 
+gRPC Server returned code: 0
+gRPC error message: 
+```