Simplify inlining code snippets in Markdown files

[tiziano88]

https://github.com/project-oak/oak/commit/4061d1dd74023c8cb5b061542490e8bbb0afaa29 introduced the use of embedmd to ensure that included snippets are up-to-date with the corresponding files.

embedmd works by specifying start and end regexps (inclusive) to include in the snippet.

It would be nice to figure out a way so that:

• we don't need to manually change the regexps every time the source code changes
• it is more obvious when we are modifying source code that is included in some snippet

A possible approach would be to include markers in comments in the source file, and figure out whether embedmd (or some other tool) can pull the code between markers, without the markers themselves.

e.g.:

https://github.com/project-oak/oak/blob/04785c2231d404fcdbe2a740eb5c08696096c9ed/docs/programming-oak.md#L55-L64

may become

[embedmd]:# (../examples/running_average/module/rust/src/lib.rs Rust /BEGIN node_instance/ /END/)

and the source code:

// BEGIN node_instance
#[derive(Default, OakExports)]
struct Node {
    sum: u64,
    count: u64,
}
// END node_instance

or something along those lines.

Note I am not sure whether embedmd already supports this mode (probably not). If not, we can look for other tools, or consider sending a patch to embedmd directly.

[tiziano88]

Worst case, we could start with the marker comments, and leave them included in the snippets. It's not great, but I personally think it is better than the current situation (others may disagree).

[daviddrysdale]

Personally, I'm not too bothered by the current setup – I prefer leaving the source code uncluttered, and the clutter in the programming-oak.md file is only visible to maintainers, not readers.

However, it might be nice to move the format checks to later in the Cloudbuild run – they're much less important than the unit & live tests, so stopping the run at the first misplaced whitespace is a bit inefficient.