Add tooling to documentation generation to ensure quality & ease maintenance of example code

[zakhenry]

Other information:

Currently documentation sample code is maintained within markdown files only, with some limitations - we have to escape everything that looks like html (e.g. Observable<T> needs to be written as Observable<T>, plus rendered markdown (what you possibly review) doesn't end up being very readable due to a lack of whitespace preformatting.

I'd suggest that we update the CodeComponent so that it selects a preformatted code block within the markdown:

before:

  <code-example header="user.effects.ts">
    const myObservable$: Observable<number> = of(1);
  </code-example>

after:

  <code-example header="user.effects.ts">
    ```ts
    const myObservable$: Observable<number> = of(1);
    ```
  </code-example>

---

Separately but related, I'd like to consider using embedme so that the embedded code is in an actual typescript file, allowing for it to be compile-checked. This practically would look like the following:

Markdown as usual, but with a snippet typescript file alongside

  <code-example header="user.effects.ts">
    <!-- embedme snippets/user.effects.ts -->
    ```ts
    const myObservable$: Observable<number> = of(1);
    ```
  </code-example>

---

What benefits will this bring?

• Documentation snippets are compiled against the current version of ngrx
• Tests can be written for documentation snippets
• Code reviews are clearer as Github will have a syntax highlighted code snippet
• No risk of invalid templates caused by html escaping (this might become particularly useful once @ngrx/component lands.

I would be willing to submit a PR for the docs ❤️

[x] Yes (Assistance is provided if you need help submitting a pull request)
[ ] No

[brandonroberts]

Thanks @zakhenry. We already have tooling in place to generate documentation from code snippets. I am however looking at retooling our underlying docs generation to be less custom, and easier to maintain by someone other than myself.

I have looked at embedme and am interested in using it as a potential solution to accomplish this. For documentation generation it works well, although I wish it had code fences in addition to specifying line numbers. There is also the challenge of generating API docs from source code. Let me know your thoughts.

[zakhenry]

I wish it had code fences in addition to specifying line numbers

can you clarify this please? - do you mean that you wish the source code could mark a labelled start and end point for insertion? That is currently an open issue, but it would be useful to know that other people want that feature too.

My thinking with this issue is specifically for the guide. I haven't looked into the API generation, but I was really just trying to solve an annoyance I had with editing code in the guide section.

[brandonroberts]

Yes, a start and end point for insertion. Our current tooling is based on the Angular Docs infrastructure, which uses a docregion to specify code fences, named and unnamed. Here is an example https://github.com/ngrx/platform/blob/master/projects/ngrx.io/content/examples/store/src/app/app.module.ts

We could create a general "snippets" area for each package, and put the snippets there and use it today to solve the issue you ran into. Or maybe a snippets example app we can pull from.