Updating docs for new ControlClient APIs

[MaciejKaszynski]

Updating docs for new ControlClient APIs

• Also added example code into the docs.

[NicolasFussberger]

I guess a problem with this scenario is that it will always go into the race condition of possibly aborting the initial transition that started state manager in the first place.

I think this can probably not be avoided as long as we only have the "force" activation.

[NicolasFussberger]

I wonder if it would be enough if we do literal include of the specific sections from the existing control daemon example for depicting the API interaction.

[MaciejKaszynski]

The examples/control_application/control_daemon.cpp has the same issue as I don't think there is any syncing between the callback and the main thread. I didn't use the control_daemon.cpp because of the custom IPC that is there which I don't think should be in the exmaple.

[NicolasFussberger]

I think the control_daemon.cpp happens to avoid this race condition because it does not directly initiate a transition after reporting kRunning, but only upon request via IPC.

I was wondering if it makes sense to reuse the examples we already have and only include certain parts into the documentation for explanation. From the sphinx docs it seemed possible like this:

// start-activate-doc
const auto result = client->activate_run_target(score::mw::lifecycle::RunTargetName{runTargetName}, true);
if (result.has_value())
{
    std::cerr << "Successfully requested Run Target " << runTargetName << std::endl;
}
else
{
    std::cerr << "Requesting Run Target " << runTargetName
              << " failed with error: " << result.error().Message() << std::endl;
}
// end-activate-doc

And then in the documentation include only the parts between the comment markers

.. literalinclude:: examples/control_application/control_daemon.cpp
   :start-after: start-activate-doc
   :end-before: end-activate-doc

Benefit would be:

• single set of examples in the repo, no duplication
• examples are built and also executed, so we are sure they are working

[NicolasFussberger]

But I also see a benefit of having these skeleton examples, so feel free to decide.

[MaciejKaszynski]

But then we'd have to copy the /examples source code into the docs folder. Docs can't see anything outside the source_dir so we'd have to copy and the actual code wouldn't run and we could get out of sync.

[MaciejKaszynski]

I fixed with atomics now

[NicolasFussberger]

Can we use a link to latest version?
Otherwise we will need to keep updating the link every time.

[MaciejKaszynski]

yeah wasn't really sure what to do because if we do latest there is a chance they will move pages and the link will not be valid.
would you say having latest is better?

[NicolasFussberger]

Not sure. But I am pretty sure we forget to align this link every release 😅
@TimoSteuerwaldETAS has some experience with automatic link checking for documentation, may we can roll this out in the repo?

[TimoSteuerwaldETAS]

I have added the link checker here: https://github.com/etas-eng/vsps_lifecycle_docs/blob/main/build_docs.sh
There it is executed now during each build. Andreas recommended to execute it once per week, but for the internal repo, as there is not much traffic anyways, I think it is fine to keep it as it is.

For the public repo I would first give it a try and check how much it increases build time. Depending on that we can set the frequency for this check.

[github-actions]

Documentation preview for this pull request is available at:
pr-796: https://eclipse-score.github.io/lifecycle/pr-796/

[NicolasFussberger]

I wonder if it is clear to the user what we refer to with "Lifecycle API" and "Lifecycle Interface".
Maybe we should clarify somewhere that this term refers to 3 APIs:
The C++ report_running function, the rust report_running function and this run_application stuff

[MaciejKaszynski]

I think it's clear now, since it can use any of them.

[NicolasFussberger]

Few small comments, but generally looks good to me.

[SimonKozik]

Looks OK to me