Improve service documentation

.devcontainer/Dockerfile

@@ -21,21 +21,23 @@ ARG VARIANT=hugo
 # VERSION can be either 'latest' or a specific version number
 ARG VERSION=latest
 
-# Download Hugo
+# Download Hugo Dependencies
 RUN apt-get update && apt-get install -y ca-certificates openssl git curl golang python-is-python3 && \
-    rm -rf /var/lib/apt/lists/* && \
-    case ${VERSION} in \
+    rm -rf /var/lib/apt/lists/*
+
+# Download Hugo
+RUN case ${VERSION} in \
     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 Hugo architecture identifier 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/devcontainer.json

@@ -41,5 +41,9 @@
 	"remoteUser": "node",
 	// Use 'postCreateCommand' to run commands after the container is created.
 	"postCreateCommand": ".devcontainer/scripts/postCreateCommand.sh",
-	"postStartCommand": "hugo server -b http://localhost/velocitas -w"
+	// Hugo needs to run in the background as otherwise postStartCommand will never finish
+	"postStartCommand":  {
+		"Information":"echo Starting documentation server at http://localhost:1313/velocitas/, see nohup.out for detailed information.",
+		"Running Hugo Server":"nohup bash -c 'hugo server -b http://localhost/velocitas -w &'"
+    }
 }

.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

@@ -19,6 +19,7 @@ on:
   push:
     branches:
       - "main"
+  pull_request:
 
 jobs:
   Build-documentation:
@@ -34,6 +35,12 @@ jobs:
           hugo-version: "0.123.3"
           extended: true
 
+      - name: Build devcontainer and do a sanity check that it starts
+        uses: devcontainers/[email protected]
+        with:
+          runCmd: |
+            ls
+
       - name: Build
         run: |
           export NODE_PATH=$NODE_PATH:`npm root -g`
@@ -53,9 +60,10 @@ jobs:
           echo -e "\`\`\`" >> $GITHUB_STEP_SUMMARY
 
       - name: Publish to GH Pages
-        # Note that gh_pages isnt published to https://eclipse-velocitas.github.io/velocitas-docs/
+        # Note that gh_pages isn't 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 :-)
+        if: ${{ github.event_name == 'push'}}
         uses: peaceiris/[email protected]
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -304,3 +304,6 @@ fabric.properties
 .idea/**/azureSettings.xml
 
 # End of https://www.toptal.com/developers/gitignore/api/hugo,node,macos,webstorm
+
+# Log file created when starting hugo by devcontainer postStartCommand
+nohup.out

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
     rev: v4.5.0
     hooks:
       - id: trailing-whitespace
-        exclude: docs
+        exclude: ^docs
       - id: end-of-file-fixer
       - id: check-yaml
         args: [--allow-multiple-documents]

README.md

@@ -1,8 +1,61 @@
-# 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 Environment
+
+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.
+
+### Release Testing
+
+Before deploying the official documentation by triggering the `Publish Documentation` workflow the following actions must be performed:
+
+* Run the hugo server on localhost
+* Verify that appearance is similar to the [currently deployed official version](https://eclipse.dev/velocitas/) and links are working as expected.
+* Upload the new `main` to a fork that you control with GitHub Pages enabled
+* Verify that you can run the `Publish Documentation` workflow and that the result is published to your pages. Use a GitHub Pages configuration where the `docs` branch is used and where the result will be available at `https://<your userid or organization>.github.io/velocitas-docs/`.
+* After triggering `Publish Documentation` workflow on the official `velocitas-docs`repository verify that results looks like expected.
+
+## Theme Upgrade
+
+Velocitas-docs use the [Docsy Theme](https://github.com/google/docsy).
+To upgrade you need to change the docsy version in [postCreateCommand.sh](.devcontainer/scripts/postCreateCommand.sh) and rebuild the devcontainer.
+This will result in updated versions of `go.mod`and `go.sum`.
 
 ## Community
 

content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/grpc_interface.md

@@ -62,7 +62,7 @@ You need to specify `devenv-devcontainer-setup` >= `v2.4.2` in your project conf
   },
   "components": [
     {
-      "id": "grpc-interface-support", 
+      "id": "grpc-interface-support",
     }
   ],
 }

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 following setup was used for the examples:
+
+* 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.
+For the server `forwardPorts": [ 5555 ]` was additionally 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 need to be performed in the shown 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.